Runs the full BearQ regression suite — every regression-ready test case in the workspace. Use for CI/CD or pre-release smoke.

Toolset: Tasks

Parameters:

• environment (string): Target environment name to run tests against. Omit to use the workspace default.

Runs specific BearQ regression test cases by ID. Targets only regression-ready cases — drafts will be rejected.

Toolset: Tasks

Parameters:

• testCaseIds (array) required: IDs of BearQ regression test cases to run.

• environment (string): Target environment name to run tests against. Omit to use the workspace default.

Runs every regression test case tagged with one or more functional areas. Functional areas can be given by ID or name.

Toolset: Tasks

Parameters:

• functionalAreas (array) required: Functional areas to target, by ID or name.

• environment (string): Target environment name to run tests against. Omit to use the workspace default.

Deletes specific BearQ test cases by ID. Deletion is reversible — tests are archived and can be restored. Works on any unprotected test; protected tests are rejected.

Toolset: Tasks

Parameters:

• testCaseIds (array) required: IDs of BearQ test cases to delete.

Explores the live application to discover or update its pages and elements in BearQ's application model. Optionally scope to a single functional area.

Toolset: Tasks

Parameters:

• functionalArea (union): Functional area to scope the exploration to, by ID or name. Omit to explore the entire application.

Sends an open-ended instruction to BearQ's QA lead agent. Use this when no other BearQ tool fits — the QA lead can list, create, and update test cases, manage functional areas, and read the application model, and acts as a general-purpose escape hatch.

Toolset: Tasks

Parameters:

• instruction (string) required: Natural language instruction to send to the BearQ QA lead agent.

Retrieves a task's current state, metadata, and activity log. Returns immediately with whatever's available — does not block on the task completing.

Toolset: Tasks

Parameters:

• taskId (number) required: BearQ task ID.

Retrieves the status of a task (running / complete / error / cancelled). Cheaper than fetching full task details.

Toolset: Tasks

Parameters:

• taskId (number) required: BearQ task ID.

Cancels a running task.

Toolset: Tasks

Parameters:

• taskId (number) required: BearQ task ID to cancel.

Blocks until a BearQ task reaches a terminal state (completed / failed / cancelled) or the stream times out, then returns the full ordered sequence of SSE events from the public API (metadata, activityLogEntries, and a terminal done or timeout event) verbatim. Blocks for the lifetime of the task — for a quick check use bearq_get_task_status instead.

Toolset: Tasks

Parameters:

• taskId (number) required: BearQ task ID.

Lists the environments configured in the workspace. Use this to discover valid environment names to pass to the test-running tools, and to identify the workspace default.

Toolset: Environments

Parameters: None

Retrieve available reusable test segments for the given platform type. Segments are reusable test steps with an optional set of parameters that can used across multiple tests.

Toolset: Tests

Parameters:

• platform (enum) required: The platform type to retrieve segments for

• offset (number): Offset for pagination

• limit (number): Maximum number of segments to return

Connect to an active Reflect recording session via WebSocket to enable interactive control. When creating or editing a Reflect test using a connected recording session, follow these guidelines:

1. After connecting to a session, get the list of segments for the session's platform type so you know what actions could be added via segments vs needing to create new steps. Do not list tests, only list segments.

2. Before performing an action, take a screenshot to understand the current state of the application.

3. Each add_prompt_step request should perform a single action or assertion. Do not combine multiple actions or assertions into a single step.

4. Only perform one action at a time unless you're sure the action won't move the application to a different screen. For example, you can send multiple add_prompt_step requests to fill out individual form fields if those fields are visible on the current screen.

5. Check the list of existing Segments to see if a Segment exists that achieves a similar goal to what you're trying to do next. If so, add the segment instead of creating new steps.

6. If a step fails, use delete_previous_step to remove it and try a different approach.

7. After completing a task, if the task required multiple prompt steps, add a final prompt step that validates the current state of the page based on what you see on the screen. In your validation, do not reference information that can change from run to run.

Toolset: Recording

Parameters:

• sessionId (string) required: The ID of the Reflect recording session to connect to

Add a natural language prompt step to an active Reflect recording session

Toolset: Recording

Parameters:

• sessionId (string) required: The ID of the Reflect recording session

• prompt (string) required: The natural language prompt describing the test step. The prompt should describe a single action, assertion, or query. The prompt can only contain literal text; it cannot contain template variables, secrets, or other dynamic syntax. If we are in a Web recording, the prompt can perform browser navigation (e.g. 'Click on the back button', 'Navigate to https://www.example.com') and use the tab and enter keys to navigate (e.g. 'Press the tab key', 'Press the enter key').

Capture a screenshot from the current state of an active Reflect recording session

Toolset: Recording

Parameters:

• sessionId (string) required: The ID of the Reflect recording session

• format (enum): The image format for the screenshot (png or jpeg)

Delete the last step added to an active Reflect recording session

Toolset: Recording

Parameters:

• sessionId (string) required: The ID of the Reflect recording session

Insert a reusable test segment into an active Reflect recording session

Toolset: Recording

Parameters:

• sessionId (string) required: The ID of the Reflect recording session

• segmentId (number) required: The ID of the segment to add

Retrieve a list of all reflect suites available

Toolset: Suites

Parameters: None

List all executions for a given suite

Toolset: Suites

Parameters:

• suiteId (string) required: ID of the reflect suite to list executions for

Get the status of a reflect suite execution

Toolset: Suites

Parameters:

• suiteId (string) required: ID of the reflect suite to get execution status for

• executionId (string) required: ID of the reflect suite execution to get status for

Execute a reflect suite

Toolset: Suites

Parameters:

• suiteId (string) required: ID of the reflect suite to execute

Cancel a reflect suite execution

Toolset: Suites

Parameters:

• suiteId (string) required: ID of the reflect suite to cancel execution for

• executionId (string) required: ID of the reflect suite execution to cancel

List all reflect tests

Toolset: Tests

Parameters: None

Get the full detail of a reflect test, including its name, description, and all recorded steps

Toolset: Tests

Parameters:

• testId (string) required: ID of the reflect test to retrieve details for

Run a reflect test

Toolset: Tests

Parameters:

• testId (string) required: ID of the reflect test to run

Get the status of a reflect test execution

Toolset: Tests

Parameters:

• executionId (string) required: ID of the reflect test execution to get status for

Create a new Reflect test which contains an ordered list of steps.

Toolset: Tests

Parameters:

• name (string) required: Name of the test to create.

• type (enum) required: Platform of the test.

• description (string): Optional description of the test.

• deviceProfile (string): Device profile id. Required for a 'web' test; ignored for 'api' and 'native-mobile'. One of: 'desktop', 'tablet', 'mobile'.

• steps (array) required: Ordered list of steps that make up the test. Web tests must begin with a 'browser-navigate' step. Prefer deterministic, selector-based steps ('click', 'input', 'submit', 'text-validation', 'hover', etc.) over AI-driven 'prompt' steps whenever a stable selector is available. Reserve 'prompt' steps for behavior that can't be expressed with a selector. Any text field in a step (e.g. 'inputText', 'url', 'expectedText', 'requestBody', header values, prompt text) may embed Reflect variable and function references using '${...}' syntax, which are resolved at run time: '${var(name)}' inserts the value of a parameter/variable named 'name' (declare parameters via the top-level 'parameters' field, or assign them mid-run with an 'update-parameters' step); '${sec(name)}' inserts the value of the account secret 'name'. Functions generate dynamic values: '${alphanum(n)}', '${alpha(n)}', '${num(n)}' (random alphanumeric / alphabetic / numeric string of length n), '${range(min, max)}' (random integer, inclusive), '${time(offsetMs)}' and '${datetime(offsetMs)}' (current epoch-millis / date-time, with an optional millisecond offset), and '${date(format, offsetDays)}' (current date formatted with tokens like 'MM/dd/yyyy', with an optional day offset).

• parameters (array): Optional named parameters (variables) for the test, each with a 'name' and optional default 'value'. Reference a parameter's value inside any step text field with '${var(name)}'.

Create a new Reflect segment which contains an ordered list of steps. Segments are reusable groups of steps that can be referenced from tests, and cannot reference other segments.

Toolset: Tests

Parameters:

• name (string) required: Name of the segment to create.

• type (enum) required: Platform of the segment.

• description (string): Optional description of the segment.

• deviceProfile (string): Device profile id. Required for a 'web' segment; ignored for 'api' and 'native-mobile'. One of: 'desktop', 'tablet', 'mobile'.

• steps (array) required: Ordered list of steps that make up the segment. Segments cannot reference other segments. Prefer deterministic, selector-based steps ('click', 'input', 'submit', 'text-validation', 'hover', etc.) over AI-driven 'prompt' steps whenever a stable selector is available. Reserve 'prompt' steps for behavior that can't be expressed with a selector. Any text field in a step (e.g. 'inputText', 'url', 'expectedText', 'requestBody', header values, prompt text) may embed Reflect variable and function references using '${...}' syntax, which are resolved at run time: '${var(name)}' inserts the value of a parameter/variable named 'name' (declare parameters via the top-level 'parameters' field, or assign them mid-run with an 'update-parameters' step); '${sec(name)}' inserts the value of the account secret 'name'. Functions generate dynamic values: '${alphanum(n)}', '${alpha(n)}', '${num(n)}' (random alphanumeric / alphabetic / numeric string of length n), '${range(min, max)}' (random integer, inclusive), '${time(offsetMs)}' and '${datetime(offsetMs)}' (current epoch-millis / date-time, with an optional millisecond offset), and '${date(format, offsetDays)}' (current date formatted with tokens like 'MM/dd/yyyy', with an optional day offset).

• parameters (array): Optional named parameters (variables) for the segment, each with a 'name' and optional default 'value'. Reference a parameter's value inside any step text field with '${var(name)}'.

Retrieve the 'current' project on which tools should operate by default. This allows BugSnag tools to be called with no projectId parameter.

Toolset: Projects

Parameters: None

Use Cases: 1. Understand if a current project has been set

Hints: 1. If a project is returned, it can be assumed that the user expects interactions with BugSnag tools to refer to this project 2. If this tool returns no current project then other BugSnag tools will require an explicit project ID parameter 3. Call the List Projects tool to see all projects that the user has access to. Get the project ID from this list either by asking the user for the project name or slug 4. You might find a BugSnag API key in the user's code where they configure the BugSnag SDK that can be matched to a project 'apiKey' field from the project list

List all projects in the organization that the current user has access to, or find a project matching an API key.

Toolset: Projects

Parameters:

• apiKey (string): The API key of the BugSnag project, if known.

Use Cases: 1. Get an overview of all projects in the organization 2. Locate a project by its API key if known from the user's code

Hints: 1. Project IDs from this list can be used with other tools when no project API key is configured

Get available event filter fields for a project

Toolset: Projects

Parameters:

• projectId (string): Unique identifier of the project. This is optional if a current project is set and is used to set the current project for BugSnag tools.

Use Cases: 1. Discover what filter fields are available before searching for errors 2. Find the correct field names for filtering by user, environment, or custom metadata 3. Understand filter options and data types for building complex queries

Examples:

1. Get all available filter fields

{}

Expected Output: JSON array of EventField objects containing display_id, custom flag, and filter/pivot options

Hints: 1. Use this tool before the List Errors or Get Error tools to understand available filters 2. Look for display_id field in the response - these are the field names to use in filters

Get full details on an error, including aggregated and summarized data across all events (occurrences) and details of the latest event (occurrence), such as breadcrumbs, metadata and the stacktrace. Use the filters parameter to narrow down the summaries further.

Toolset: Errors

Parameters:

• projectId (string): Unique identifier of the project. This is optional if a current project is set and is used to set the current project for BugSnag tools.

• errorId (string) required: Unique identifier of the error to retrieve

• filters (record<string, array>): Apply filters to narrow down the error list. Use the List Project Event Filters tool to discover available filter fields. Time filters support extended ISO 8601 format (e.g. 2018-05-20T00:00:00Z) or relative format (e.g. 7d, 24h). (default: {"event.since":[{"type":"eq","value":"30d"}],"error.status":[{"type":"eq","value":"open"}]})

Output Description: JSON object containing: - error_details: Aggregated data about the error, including first and last seen occurrence - latest_event: Detailed information about the most recent occurrence of the error, including stacktrace, breadcrumbs, user and context - pivots: List of pivots (summaries) for the error, which can be used to analyze patterns in occurrences - url: A link to the error in the dashboard - this should be shown to the user for them to perform further analysis

Use Cases: 1. Investigate a specific error found through the List Project Errors tool 2. Understand which types of user are affected by the error using summarized event data 3. Get error details for debugging and root cause analysis 4. Retrieve error metadata for incident reports and documentation

Examples:

1. Get details for a specific error

{
  "errorId": "6863e2af8c857c0a5023b411"
}

Expected Output: JSON object with error details including message, stack trace, occurrence count, and metadata

Hints: 1. Error IDs can be found using the List Project Errors tool 2. Use this after filtering errors to get detailed information about specific errors 3. Use Get Event Details tool if you need detailed information about a specific event (occurrence) rather than the aggregated error 4. If you used a filter to get this error, you can pass the same filters here to restrict the results or apply further filters 5. The URL provided in the response points should be shown to the user in all cases as it allows them to view the error in the dashboard and perform further analysis

List and search errors in a project using customizable filters and pagination

Toolset: Errors

Parameters:

• projectId (string): Unique identifier of the project. This is optional if a current project is set and is used to set the current project for BugSnag tools.

• filters (record<string, array>): Apply filters to narrow down the error list. Use the List Project Event Filters tool to discover available filter fields. Time filters support extended ISO 8601 format (e.g. 2018-05-20T00:00:00Z) or relative format (e.g. 7d, 24h). (default: {"event.since":[{"type":"eq","value":"30d"}],"error.status":[{"type":"eq","value":"open"}]})

• sort (enum): Field to sort the errors by (default: "last_seen")

• direction (enum): Sort direction for ordering results (default: "desc")

• perPage (number): How many results to return per page. (default: 30)

• nextUrl (string): URL for retrieving the next page of results. Use the value in the previous response to get the next page when more results are available. Only values provided in the output from this tool can be used. Do not attempt to construct it manually.

Use Cases: 1. Debug recent application errors by filtering for open errors in the last 7 days 2. Generate error reports for stakeholders by filtering specific error types or severity levels 3. Monitor error trends over time using date range filters 4. Find errors affecting specific users or environments using metadata filters

Examples:

1. Find errors affecting a specific user in the last 24 hours

{
  "filters": {
    "user.email": [
      {
        "type": "eq",
        "value": "user@example.com"
      }
    ],
    "event.since": [
      {
        "type": "eq",
        "value": "24h"
      }
    ]
  }
}

Expected Output: JSON object with a list of errors in the 'data' field, a count of the current page of results in the 'count' field, and a total count of all results in the 'total' field

2. Get the 10 open errors with the most users affected in the last 30 days

{
  "filters": {
    "event.since": [
      {
        "type": "eq",
        "value": "30d"
      }
    ],
    "error.status": [
      {
        "type": "eq",
        "value": "open"
      }
    ]
  },
  "sort": "users",
  "direction": "desc",
  "perPage": 10
}

Expected Output: JSON object with a list of errors in the 'data' field, a count of the current page of results in the 'count' field, and a total count of all results in the 'total' field

3. Get the next 50 results

{
  "nextUrl": "https://api.bugsnag.com/projects/515fb9337c1074f6fd000003/errors?base=2025-08-29T13%3A11%3A37Z&direction=desc&filters%5Berror.status%5D%5B%5D%5Btype%5D=eq&filters%5Berror.status%5D%5B%5D%5Bvalue%5D=open&offset=10&per_page=10&sort=users",
  "perPage": 50
}

Expected Output: JSON object with a list of errors, with a URL to the next page if more results are available and a total count of all errors matched

Hints: 1. Use List Project Event Filters tool first to discover valid filter field names for your project 2. Combine multiple filters to narrow results - filters are applied with AND logic 3. For time filters: use relative format (7d, 24h) for recent periods or ISO 8601 UTC format (2018-05-20T00:00:00Z) for specific dates 4. Common time filters: event.since (from this time), event.before (until this time) 5. The 'event.since' filter and 'error.status' filters are always applied and if not specified are set to '30d' and 'open' respectively 6. There may not be any errors matching the filters - this is not a problem with the tool, in fact it might be a good thing that the user's application had no errors 7. This tool returns paged results. The 'page_error_count' field indicates the number of results returned in the current page, and the 'total_error_count' field indicates the total number of results across all pages. 8. If the output contains a 'next_url' value, there are more results available - call this tool again supplying the next URL as a parameter to retrieve the next page. 9. Do not modify the next URL as this can cause incorrect results. The only other parameter that can be used with 'next' is 'per_page' to control the page size.

Update the status of an error

Toolset: Errors

Parameters:

• projectId (string): Unique identifier of the project. This is optional if a current project is set and is used to set the current project for BugSnag tools.

• errorId (string) required: Unique identifier of the error

• operation (enum) required: The operation to apply to the error

• issue_url (string): The URL of the issue to link to the error - required when operation is 'link_issue'

• reopenRules (object): Reopen rules for snooze operation - required when operation is 'snooze'

Use Cases: 1. Mark an error as open, fixed or ignored 2. Discard or un-discard an error 3. Update the severity of an error 4. Snooze an error with defined conditions for when it should be reopened

Examples:

1. Mark an error as fixed

{
  "errorId": "6863e2af8c857c0a5023b411",
  "operation": "fix"
}

Expected Output: Success response indicating the error was marked as fixed

2. Snooze an error for 1 hour

{
  "errorId": "6863e2af8c857c0a5023b411",
  "operation": "snooze",
  "reopenRules": {
    "reopenIf": "occurs_after",
    "seconds": 3600
  }
}

Expected Output: Success response indicating the error was snoozed for 1 hour

3. Snooze an error until 5 additional users are affected

{
  "errorId": "6863e2af8c857c0a5023b411",
  "operation": "snooze",
  "reopenRules": {
    "reopenIf": "n_additional_users",
    "additionalUsers": 5
  }
}

Expected Output: Success response indicating the error was snoozed until 5 additional users are affected

4. Snooze an error until 10 occurrences in 24 hours

{
  "errorId": "6863e2af8c857c0a5023b411",
  "operation": "snooze",
  "reopenRules": {
    "reopenIf": "n_occurrences_in_m_hours",
    "occurrences": 10,
    "hours": 24
  }
}

Expected Output: Success response indicating the error was snoozed until 10 occurrences in 24 hours

5. Link a Jira issue to an error

{
  "errorId": "6863e2af8c857c0a5023b411",
  "operation": "link_issue",
  "issue_url": "https://smartbear.atlassian.net/browse/PIPE-9547"
}

Expected Output: Success response indicating the Jira issue was linked to the error

6. Unlink a Jira issue from an error

{
  "errorId": "6863e2af8c857c0a5023b411",
  "operation": "unlink_issue"
}

Expected Output: Success response indicating the Jira issue was unlinked from the error

Hints: 1. Only use valid operations - BugSnag may reject invalid values 2. When using 'snooze' operation, reopenRules parameter is required 3. When using 'link_issue' operation, issue_url parameter is required 4. Use 'unlink_issue' to remove the link between an error and its issue 5. For 'occurs_after' reopen rules, specify 'seconds' parameter 6. For 'n_additional_users' reopen rules, specify 'additionalUsers' parameter (max 100,000) 7. For 'n_occurrences_in_m_hours' reopen rules, specify both 'occurrences' and 'hours' parameters 8. For 'n_additional_occurrences' reopen rules, specify 'additionalOccurrences' parameter 9. Snoozing temporarily silences an error until the specified reopen condition is met

Get detailed information about a specific event

Toolset: Events

Parameters:

• projectId (string): Unique identifier of the project. This is optional if a current project is set and is used to set the current project for BugSnag tools.

• eventId (string) required: Unique identifier of the event

Use Cases: 1. Get the full details of an event, including any thread stack traces

Examples:

1. Get event details of an event

{
  "eventId": "6863e2af012caf1d5c320000"
}

Expected Output: JSON object with complete event details including stack trace (error trace and other threads, if present), metadata, and context

Get detailed information about a specific event using its dashboard URL

Toolset: Events

Parameters:

• link (string) required: Full URL to the event details page in the BugSnag dashboard (web interface), containing project slug and event_id parameter.

Use Cases: 1. Get event details when given a dashboard URL from a user or notification 2. Extract event information from shared links or browser URLs 3. Quick lookup of event details without needing separate project and event IDs

Examples:

1. Get event details from a dashboard URL

{
  "link": "https://app.bugsnag.com/my-org/my-project/errors/6863e2af8c857c0a5023b411?event_id=6863e2af012caf1d5c320000"
}

Expected Output: JSON object with complete event details including stack trace, metadata, and context

Hints: 1. The URL must contain both project slug in the path and event_id in query parameters 2. This is useful when users share BugSnag dashboard URLs and you need to extract the event data

Gets a list of events that have grouped into the specified error

Toolset: Events

Parameters:

• projectId (string): Unique identifier of the project. This is optional if a current project is set and is used to set the current project for BugSnag tools.

• errorId (string) required: Unique identifier of the error

• filters (record<string, array>): Apply filters to narrow down the event list. Use the List Project Event Filters tool to discover available filter fields. Time filters support extended ISO 8601 format (e.g. 2018-05-20T00:00:00Z) or relative format (e.g. 7d, 24h). (default: {"event.since":[{"type":"eq","value":"30d"}],"error.status":[{"type":"eq","value":"open"}]})

• direction (enum): Sort direction for ordering results (default: "desc")

• perPage (number): How many results to return per page. (default: 30)

• nextUrl (string): URL for retrieving the next page of results. Use the value in the previous response to get the next page when more results are available. Only values provided in the output from this tool can be used. Do not attempt to construct it manually.

Use Cases: 1. Retrieving all the events for comparison to find commonalities or differences in stack traces, breadcrumbs and metadata

Examples:

1. Get events of an error

{
  "projectId": "1234567890abcdef12345678",
  "errorId": "6863e2af012caf1d5c320000"
}

Expected Output: A list of events, ordered by timestamp, with complete details including stack trace, breadcrumbs, metadata, and context

List releases for a project

Toolset: Releases

Parameters:

• projectId (string): Unique identifier of the project. This is optional if a current project is set and is used to set the current project for BugSnag tools.

• releaseStage (string): Filter releases by this stage (e.g. production, staging), defaults to 'production' (default: "production")

• visibleOnly (boolean): Whether to only include releases that are marked as visible in the dashboard (default: false)

• perPage (number): How many results to return per page. (default: 30)

• nextUrl (string): URL for retrieving the next page of results. Use the value in the previous response to get the next page when more results are available. Only values provided in the output from this tool can be used. Do not attempt to construct it manually.

Output Description: JSON array of release summary objects with metadata, with a URL to the next page if more results are available

Use Cases: 1. View recent releases to correlate with error spikes 2. Filter releases by stage (e.g. production, staging) for targeted analysis

Examples:

1. List production releases for a project

{}

Expected Output: JSON array of release objects in the production stage

2. List staging releases for a project

{
  "releaseStage": "staging"
}

Expected Output: JSON array of release objects in the staging stage

3. Get the next page of results

{
  "nextUrl": "/projects/515fb9337c1074f6fd000003/releases?offset=30&per_page=30"
}

Expected Output: JSON array of release objects with metadata from the next page

Hints: 1. Use the Get Release tool to get more details on a specific release, including the builds it contains 2. The release stage defaults to 'production' if not specified 3. Use visibleOnly to filter out releases that have been marked as hidden in the dashboard

Get more details for a specific release by its ID, including source control information and associated builds

Toolset: Releases

Parameters:

• projectId (string): Unique identifier of the project. This is optional if a current project is set and is used to set the current project for BugSnag tools.

• releaseId (string) required: Unique identifier of the app release

Output Description: JSON object containing release details along with stability metrics such as user and session stability, and whether it meets project targets

Use Cases: 1. View release metadata such as version, source control info, and error counts 2. Analyze the stability data and targets for a release 3. See the builds that make up the release

Examples:

1. Get details for a specific release

{
  "releaseId": "5f8d0d55c9e77c0017a1b2c3"
}

Expected Output: JSON object with release details including version, source control info, error counts and stability data.

Hints: 1. Release IDs can be found using the List releases tool

Get more details for a specific build by its ID

Toolset: Releases

Parameters:

• projectId (string): Unique identifier of the project. This is optional if a current project is set and is used to set the current project for BugSnag tools.

• buildId (string) required: Unique identifier of the app build

Output Description: JSON object containing build details along with stability metrics such as user and session stability, and whether it meets project targets

Use Cases: 1. View build metadata such as version, source control info, and error counts 2. Analyze a specific build to correlate with error spikes or deployments 3. See the stability targets for a project and if the build meets them

Examples:

1. Get details for a specific build

{
  "buildId": "5f8d0d55c9e77c0017a1b2c3"
}

Expected Output: JSON object with build details including version, source control info, error counts and stability data.

Hints: 1. Build IDs can be found using the List builds tool

List span groups (operations) tracked for performance monitoring

Toolset: Performance

Parameters:

• projectId (string): Unique identifier of the project. This is optional if a current project is set and is used to set the current project for BugSnag tools.

• sort (enum): Field to sort by

• direction (enum): Sort direction for ordering results (default: "desc")

• perPage (number): How many results to return per page. (default: 30)

• starredOnly (boolean): Show only starred span groups

• nextUrl (string): URL for retrieving the next page of results. Use the value in the previous response to get the next page when more results are available. Only values provided in the output from this tool can be used. Do not attempt to construct it manually.

• filters (record<string, array>): Apply filters to narrow down the span group list. Use the List Trace Fields tool to discover available filter fields. Time filters support extended ISO 8601 format (e.g. 2018-05-20T00:00:00Z) or relative format (e.g. 7d, 24h). (default: {"span.since":[{"type":"eq","value":"7d"}]})

Use Cases: 1. View all operations being tracked for performance 2. Find slow operations by sorting by duration metrics 3. Filter to starred/important span groups

Examples:

1. List slowest operations

{
  "sort": "duration_p95",
  "direction": "desc",
  "perPage": 10
}

Expected Output: Array of span groups sorted by 95th percentile duration

2. List starred span groups with filtering

{
  "starredOnly": true,
  "filters": {
    "span_group.category": [
      {
        "type": "eq",
        "value": "full_page_load"
      }
    ]
  }
}

Expected Output: Array of starred span groups filtered by category

Hints: 1. Span groups represent different operation types (page loads, API calls, etc.) 2. Use sort by duration_p95 or duration_p99 to find the slowest operations 3. Star important span groups for quick access 4. Use nextUrl for pagination

Get detailed performance metrics for a specific span group

Toolset: Performance

Parameters:

• projectId (string): Unique identifier of the project. This is optional if a current project is set and is used to set the current project for BugSnag tools.

• spanGroupId (string) required: ID of the span group

• filters (record<string, array>): Apply filters to narrow down the span group list. Use the List Trace Fields tool to discover available filter fields. Time filters support extended ISO 8601 format (e.g. 2018-05-20T00:00:00Z) or relative format (e.g. 7d, 24h). (default: {"span.since":[{"type":"eq","value":"7d"}]})

Use Cases: 1. View detailed statistics (p50, p75, p90, p95, p99) for an operation 2. Check if performance targets are configured 3. Monitor span count to understand operation volume

Examples:

1. Get details for an API endpoint span group

{
  "spanGroupId": "[HttpClient]GET-api.example.com"
}

Expected Output: Statistics, category, and performance target info

2. Get span group details with device filtering

{
  "spanGroupId": "[HttpClient]GET-api.example.com",
  "filters": {
    "device.browser_name": [
      {
        "type": "eq",
        "value": "Chrome"
      }
    ]
  }
}

Expected Output: Statistics filtered for Chrome browser only

Hints: 1. Use List Span Groups first to discover available span group IDs 2. IDs are automatically URL-encoded - provide the raw ID 3. Statistics include p50, p75, p90, p95, p99 percentiles

Get individual spans belonging to a span group

Toolset: Performance

Parameters:

• projectId (string): Unique identifier of the project. This is optional if a current project is set and is used to set the current project for BugSnag tools.

• spanGroupId (string) required: ID of the span group

• sort (enum): Field to sort by

• direction (enum): Sort direction for ordering results (default: "desc")

• perPage (number): How many results to return per page. (default: 30)

• nextUrl (string): URL for retrieving the next page of results. Use the value in the previous response to get the next page when more results are available. Only values provided in the output from this tool can be used. Do not attempt to construct it manually.

• filters (record<string, array>): Apply filters to narrow down the span group list. Use the List Trace Fields tool to discover available filter fields. Time filters support extended ISO 8601 format (e.g. 2018-05-20T00:00:00Z) or relative format (e.g. 7d, 24h). (default: {"span.since":[{"type":"eq","value":"7d"}]})

Use Cases: 1. Analyze individual slow operations 2. Debug performance issues by examining specific traces 3. Find patterns in operation attributes

Examples:

1. Get slowest spans for an operation

{
  "spanGroupId": "[HttpClient]GET-api.example.com",
  "sort": "duration",
  "direction": "desc",
  "perPage": 10
}

Expected Output: Array of the 10 slowest span instances

2. Get spans filtered by OS with pagination

{
  "spanGroupId": "[HttpClient]GET-api.example.com",
  "sort": "timestamp",
  "filters": {
    "os.name": [
      {
        "type": "eq",
        "value": "iOS"
      }
    ]
  },
  "nextUrl": "/projects/123/spans?offset=30&per_page=30"
}

Expected Output: Array of spans from iOS devices with next page navigation

Hints: 1. Sort by duration descending to find the slowest instances 2. Each span includes trace ID for further investigation

Get all spans within a specific trace

Toolset: Performance

Parameters:

• projectId (string): Unique identifier of the project. This is optional if a current project is set and is used to set the current project for BugSnag tools.

• traceId (string) required: Trace ID

• from (string) required: Start time (ISO 8601 format)

• to (string) required: End time (ISO 8601 format)

• targetSpanId (string): Optional target span ID to focus on

• perPage (number): How many results to return per page. (default: 30)

• nextUrl (string): URL for retrieving the next page of results. Use the value in the previous response to get the next page when more results are available. Only values provided in the output from this tool can be used. Do not attempt to construct it manually.

Use Cases: 1. Debug slow requests by viewing all operations in the trace 2. Understand the flow of a request through the system 3. Identify bottlenecks in distributed systems

Examples:

1. Get all spans for a trace

{
  "traceId": "abc123",
  "from": "2024-01-01T00:00:00Z",
  "to": "2024-01-01T23:59:59Z"
}

Expected Output: Array of all spans in the trace with timing and hierarchy

2. Get spans for a trace with pagination and target span

{
  "traceId": "def456",
  "from": "2024-01-01T00:00:00Z",
  "to": "2024-01-01T23:59:59Z",
  "targetSpanId": "span-789",
  "perPage": 50
}

Expected Output: Array of up to 50 spans focused around the target span

Hints: 1. Traces show the complete execution path of a request 2. Use from/to parameters to narrow the time window 3. targetSpanId can be used to focus on a specific span in the trace

Get available trace fields/attributes for filtering

Toolset: Performance

Parameters:

• projectId (string): Unique identifier of the project. This is optional if a current project is set and is used to set the current project for BugSnag tools.

Use Cases: 1. Find available custom attributes for performance filtering 2. Understand what metadata is attached to traces 3. Build dynamic filters based on available fields

Examples:

1. Get all trace fields

{}

Expected Output: Array of field names and types available for filtering

Hints: 1. Trace fields are custom attributes added to spans 2. Use these fields for filtering other performance queries

Get the network endpoint grouping rules for a project

Toolset: Performance

Parameters:

• projectId (string): Unique identifier of the project. This is optional if a current project is set and is used to set the current project for BugSnag tools.

Use Cases: 1. View current network endpoint grouping configuration 2. Understand how network requests are being grouped in performance monitoring 3. Check grouping patterns before making updates

Examples:

1. Get network grouping rules for a project

{}

Expected Output: Array of endpoint URL patterns

Hints: 1. Network grouping patterns help consolidate similar requests into single span groups 2. Patterns use OpenAPI path templating syntax with curly braces for path parameters (e.g., /users/{userId}) 3. Wildcards () can be used in domains to match multiple subdomains (e.g., https://.example.com)

Set the network endpoint grouping rules for a project

Toolset: Performance

Parameters:

• projectId (string): Unique identifier of the project. This is optional if a current project is set and is used to set the current project for BugSnag tools.

• endpoints (array) required: Array of URL patterns by which network spans are grouped. Endpoints follow OpenAPI path templating syntax (https://swagger.io/specification/#path-templating) where path parameters use curly braces (e.g., /users/{id}). If you encounter colon-prefixed parameters (e.g., :userId from Express/React Router), convert them to curly braces (e.g., {userId}). Wildcards () can be used in domains (e.g., https://.example.com) to match multiple subdomains.

Use Cases: 1. Consolidate similar API endpoints into single span groups 2. Group dynamic URLs using path parameters (e.g., /api/users/{userId} groups /api/users/123, /api/users/456) 3. Match multiple subdomains using wildcards (e.g., https://*.example.com groups api.example.com, cdn.example.com) 4. Simplify performance monitoring by reducing span group clutter

Examples:

1. Group API endpoints with path parameters

{
  "endpoints": [
    "/api/users/{userId}",
    "/api/products/{productId}",
    "/api/orders/{orderId}/items/{itemId}"
  ]
}

Expected Output: Success response confirming the update

2. Group endpoints with domain wildcards and path parameters

{
  "endpoints": [
    "https://*.example.com/api/v1/{resourceId}",
    "https://api.example.com/v2/users/{userId}",
    "/graphql"
  ]
}

Expected Output: Success response confirming the update

3. Convert colon-prefixed parameters to curly braces (e.g., from Express/React Router)

{
  "endpoints": [
    "/{organizationSlug}/{projectSlug}/performance/view-load",
    "/api/{version}/items/{itemId}"
  ]
}

Expected Output: Success response confirming the update

Hints: 1. Use Get Network Grouping first to see current patterns 2. Use OpenAPI path templating with curly braces for path parameters: /users/{userId}, /orders/{orderId}/items/{itemId} 3. Convert colon-prefixed parameters to curly braces: :organizationSlug becomes {organizationSlug}, :projectSlug becomes {projectSlug} 4. Wildcards () can be used in domains to match subdomains: https://.example.com/api 5. This replaces all existing patterns - include all patterns you want to keep 6. Well-designed patterns reduce noise in performance monitoring

Search for available portals within Swagger. Only portals where you have at least a designer role, either at the product level or organization level, are returned.

Toolset: Portals

Create a new portal within Swagger.

Toolset: Portals

Parameters:

• name (string): The display name for the portal - shown to users and in branding (3-40 characters)

• subdomain (string) required: The portal subdomain - used in the portal URL (e.g., 'myportal' for myportal.example.com). Must be unique, lowercase, 3-20 characters, alphanumeric with hyphens. Recommended: slugified organization name plus a random 3-character suffix (e.g., 'acmecorp-k7p') to avoid collisions

• offline (boolean): If true, the portal will not be visible to customers - useful for development/staging environments. Defaults to false

• routing (string): Routing strategy for the portal - either 'browser' (client-side routing) or 'proxy' (server-side routing). Defaults to 'browser'

• credentialsEnabled (boolean): Whether authentication credentials are enabled for accessing the portal. When true, users can authenticate to access private content. Defaults to true

• swaggerHubOrganizationId (string) required: The corresponding Swagger organization UUID - required for portal creation. This links the portal to your Swagger organization. Only one Portal per Swagger organization is allowed.

• openapiRenderer (string): OpenAPI renderer type: 'SWAGGER_UI' (Swagger UI), 'ELEMENTS' (Stoplight Elements), or 'TOGGLE' (allows switching between both with Elements as default). Defaults to 'TOGGLE'

• pageContentFormat (string): Format for page content rendering - determines how documentation pages are processed: 'HTML', 'MARKDOWN', or 'BOTH'. Defaults to 'HTML'

Retrieve information about a specific portal.

Toolset: Portals

Parameters:

• portalId (string) required: Portal UUID or subdomain - unique identifier for the portal instance

Update a specific portal's configuration.

Toolset: Portals

Parameters:

• portalId (string) required: Portal UUID or subdomain - unique identifier for the portal instance

• name (string): Update the portal display name - shown to users and in branding (3-40 characters)

• subdomain (string): Update the portal subdomain - changes the portal URL. Must remain unique across all portals (3-20 characters, lowercase, alphanumeric with hyphens)

• customDomain (boolean): Enable/disable custom domain for the portal - allows using your own domain instead of the default subdomain

• gtmKey (string): Google Tag Manager key for analytics tracking - format: GTM-XXXXXX (max 25 characters)

• offline (boolean): Set portal visibility - true hides portal from customers (useful for maintenance or development)

• routing (string): Update routing strategy - 'browser' for client-side routing or 'proxy' for server-side routing

• credentialsEnabled (boolean): Enable/disable authentication credentials for portal access - controls whether users can authenticate to view private content

• openapiRenderer (string): Change OpenAPI renderer: 'SWAGGER_UI' (Swagger UI), 'ELEMENTS' (Stoplight Elements), or 'TOGGLE' (switch between both)

• pageContentFormat (string): Update page content format for documentation rendering: 'HTML', 'MARKDOWN', or 'BOTH'

Resolve portal details for a Swagger organization in a single step. Given an organization UUID, returns the portal ID, subdomain, customDomain (when configured), and the list of products (with productId, productSlug, and productName) for the organization's portal. If the organization has no portal yet, a new portal is created automatically. Use this tool to obtain all portal context needed for subsequent portal and product operations.

Toolset: Portals

Parameters:

• organizationId (string) required: Swagger organization UUID - the organization to resolve portal details for

Get products for a specific portal that match your criteria.

Toolset: Products

Parameters:

• portalId (string) required: Portal UUID or subdomain - unique identifier for the portal instance

Create a new product for a specific portal.

Toolset: Products

Parameters:

• portalId (string) required: Portal UUID or subdomain - unique identifier for the portal instance

• type (string) required: Product creation type - 'new' to create from scratch or 'copy' to duplicate an existing product

• productId (string): Source product UUID to copy from - required when type is 'copy', specifies which existing product to duplicate. Omit when type is 'new'

• name (string) required: Product display name - will be shown to users in the portal navigation and product listings (3-40 characters)

• slug (string) required: URL-friendly identifier for the product - must be unique within the portal, used in URLs (e.g., 'my-api' becomes /my-api). 3-22 characters, lowercase, alphanumeric with hyphens, underscores, or dots

• description (string): Product description - explains what the API/product does, shown in product listings and cards (max 110 characters)

• public (boolean): Whether the product is publicly visible to all portal visitors - false means only authenticated users with appropriate roles can access it

• hidden (boolean): Whether the product is hidden from the portal landing page navigation menus - useful for internal or draft products

Retrieve information about a specific product resource.

Toolset: Products

Parameters:

• productId (string) required: Product UUID or identifier in the format 'portal-subdomain:product-slug' - unique identifier for the product

Delete a product from a specific portal

Toolset: Products

Parameters:

• productId (string) required: Product UUID or identifier in the format 'portal-subdomain:product-slug' - unique identifier for the product

Update a product's settings within a specific portal.

Toolset: Products

Parameters:

• productId (string) required: Product UUID or identifier in the format 'portal-subdomain:product-slug' - unique identifier for the product

• name (string): Update product display name - changes how it appears to users in navigation and listings (3-40 characters)

• slug (string): Update URL-friendly identifier - must remain unique within the portal, affects product URLs (3-22 characters, lowercase, alphanumeric with hyphens/underscores/dots)

• description (string): Update product description - explains the API/product functionality, shown in listings (max 110 characters)

• public (boolean): Change product visibility - true makes it publicly accessible to all visitors, false restricts to authenticated users with roles

• hidden (boolean): Change navigation visibility - true hides from portal landing page menus while keeping the product accessible via direct links

Publish a product's content to make it live or as preview. This endpoint publishes the current content of a product, making it visible to portal visitors. Use preview mode to test before going live. Optionally provide tableOfContentsId to get a page-specific URL. Returns publication status, a live or preview URL (null if URL building fails), product and portal metadata, and an optional warning when metadata/URL building failed — a warning does NOT mean the publish failed.

Toolset: Products

Parameters:

• productId (string) required: Product UUID or identifier in the format 'portal-subdomain:product-slug' - unique identifier for the product

• tableOfContentsId (string): Optional table of contents UUID, or identifier in the format 'portal-subdomain:product-slug:section-slug:table-of-contents-slug'. When provided, publishPortalProduct uses it to resolve the published URL path for the returned preview/live link.

• preview (boolean): Whether to publish as preview (true) or live (false). Preview allows testing before going live. Defaults to false (live publication) (default: false)

Get sections for a specific product within a portal.

Toolset: Sections

Parameters:

• productId (string) required: Product UUID or identifier in the format 'portal-subdomain:product-slug' - unique identifier for the product

• embed (array): List of related entities to embed in the response - e.g., ['tableOfContents', 'tableOfContents.swaggerhubApi'] to include table of contents and SwaggerHub API details

• page (number): Page number for paginated results - specifies which page of results to retrieve (default is 1)

• size (number): Number of items per page for pagination - controls how many results are returned per page (default is 10)

Create a new table of contents item in a portal product section. Supports API references, HTML content, and Markdown content types.

Toolset: Table Of Contents

Parameters:

• sectionId (string) required: Section ID - unique identifier for the section within the product

• type (enum) required: Type of table of contents creation - 'new' to create from scratch or 'copy' to duplicate an existing one

• title (string) required: Title of the table of contents item - will be displayed in navigation (3-40 characters)

• slug (string) required: URL-friendly identifier for the table of contents item - must be unique within the section (3-22 characters, lowercase, alphanumeric with hyphens/underscores/dots)

• order (number) required: Order position of the table of contents item within its parent section or item

• parentId (string): Parent table of contents item ID - null for top-level items, or ID of parent item for nested structure

• content (object): Content configuration for the table of contents item

Get table of contents for a section of a product within a portal.

Toolset: Table Of Contents

Parameters:

• sectionId (string) required: Section ID - unique identifier for the section within the product

• embed (array): List of related entities to embed in the response - e.g., ['swaggerhubApi'] to include SwaggerHub API details

• page (number): Page number for paginated results - specifies which page of results to retrieve (default is 1)

• size (number): Number of items per page for pagination - controls how many results are returned per page (default is 20)

Delete table of contents entry. Performs a soft-delete of an entry from the table of contents. Supports recursive deletion of nested items.

Toolset: Table Of Contents

Parameters:

• tableOfContentsId (string) required: The table of contents UUID, or identifier in the format 'portal-subdomain:product-slug:section-slug:table-of-contents-slug'

• recursive (boolean): Flag to include all the nested tables of contents (default: false)

Create a documentation page in a portal product in a single tool call. Supports markdown and html content types. Returns the page location details (productId, sectionId, slug) and a draftUrl to edit it in the portal.

Toolset: Documents

Parameters:

• portalId (string) required: Portal UUID or subdomain - unique identifier for the portal

• productId (string) required: Product UUID - unique identifier for the product

• pageTitle (string) required: Title of the documentation page - will be displayed in navigation (3-255 characters)

• pageSlug (string): URL slug for the documentation page. 3-255 characters, lowercase, alphanumeric with hyphens, underscores, or dots (e.g. 'my-page'). If not provided, the slug is generated from the page title.

• pageContent (string): Content of the documentation page. Provide HTML when contentType is 'html', Markdown when contentType is 'markdown'.

• contentType (enum): Content type of the documentation page. 'markdown' works with both 'internal' and 'external' source. 'html' only works with 'external' source — html + internal is not supported by the API and will return an error. (default: "markdown")

• source (enum): Where the document content is managed. 'internal': editable in both the portal UI and via API. 'external': editable via API only, not in the portal UI. Constraint: 'html' content type only supports 'external' source. (default: "internal")

• order (number): Order position of the documentation page within its parent section or item (default: 0)

• parentId (string): Parent table of contents item ID - null for top-level pages, or ID of parent item for nested structure

Get document content and metadata by document ID. Useful for retrieving HTML or Markdown content from table of contents items.

Toolset: Documents

Parameters:

• documentId (string) required: Document UUID - unique identifier for the document

Update the content or source of an existing document. Supports both HTML and Markdown content types.

Toolset: Documents

Parameters:

• documentId (string) required: Document UUID - unique identifier for the document

• content (string): The document content to update (HTML or Markdown based on document type)

• type (enum): Content type of the document. Note: documents with type 'html' and source 'internal' cannot be edited via API — only 'html' + 'external' and all 'markdown' combinations are supported.

• source (enum): Where the document content is managed. 'internal': editable in both portal UI and API. 'external': editable via API only. Note: 'html' + 'internal' documents cannot be updated via API.

Search for APIs and Domains in SwaggerHub Registry using the comprehensive /specs endpoint and retrieve metadata including owner, name, description, summary, version, and specification.

Toolset: Registry API

Parameters:

• query (string): Search query to filter APIs by name, description, or content

• state (enum): Filter APIs by publication state - ALL (default), PUBLISHED, or UNPUBLISHED

• tag (string): Filter APIs by tag

• offset (number): Offset for pagination (0-based, default 0)

• limit (number): Number of results per page (1-100, default 20)

• sort (enum): Sort field - NAME, UPDATED, or CREATED (default NAME)

• order (enum): Sort order - ASC or DESC (default ASC)

• owner (string): Filter APIs by owner (organization or user)

• specType (enum): Filter by specification type - API or DOMAIN (default all types)

Fetch resolved API definition from SwaggerHub Registry based on owner, API name, and version. By default returns the definition as JSON (converting YAML-stored definitions to JSON). Set format:'text' to get the YAML definition — required as the source for swagger_patch_api edits.

Toolset: Registry API

Parameters:

• owner (string) required: API owner (organization or user, case-sensitive)

• api (string) required: API name (case-sensitive)

• version (string) required: Version identifier

• resolved (boolean): Set to true to get the resolved version with all external $refs included (default false)

• flatten (boolean): Set to true to create models from inline schemas in OpenAPI definition (default false)

• format (enum): Response format: 'json' (default) may convert YAML to JSON; 'text' returns the definition as YAML — required for swagger_patch_api edits.

Create a new API or update an existing API in SwaggerHub Registry for Swagger Studio. The API specification type (OpenAPI, AsyncAPI) is automatically detected from the definition content. APIs are always created with fixed values: version 1.0.0, private visibility, and automock disabled (these values cannot be changed). Returns HTTP 201 for creation, HTTP 200 for update. Response includes 'operation' field indicating whether it was a 'create' or 'update' operation along with API details and SwaggerHub URL.

Toolset: Registry API

Parameters:

• owner (string) required: Organization name (owner of the API)

• apiName (string) required: API name

• definition (string) required: API definition content (OpenAPI/AsyncAPI specification in JSON or YAML format). Format is automatically detected. On create, fixed values are used: version 1.0.0, private visibility, automock disabled, and no project assignment. On update, the API's existing visibility is preserved.

Get organizations for a user. Returns a list of organizations that the authenticating user is a member of. On-Premise admin gets a list of all organizations in the system.

Toolset: Registry API

Parameters:

• q (string): Search organizations by partial or full name (case-insensitive)

• sortBy (enum): The property to sort the results by

• order (enum): Sort order

• page (number): 0-based index of the page to return

• pageSize (number): Number of results per page to return

Run a standardization scan against an API definition using the organization's governance and standardization rules. Accepts a raw YAML or JSON OpenAPI/AsyncAPI definition and returns a list of validation errors, the total issue count, and counts grouped by severity. Use this tool when the user provides the API definition content directly (as raw YAML or JSON) and asks to validate, scan, or check the governance or standardization of the API.

Toolset: Registry API

Parameters:

• orgName (string) required: The organization name to use for standardization rules

• definition (string) required: API definition content (OpenAPI/AsyncAPI specification in JSON or YAML format) to scan for standardization errors

Run a standardization scan on an API that already exists in SwaggerHub Registry, identified by organization name, API name, and version. Fetches the API definition from the registry internally and scans it against the organization's governance and standardization rules. Returns a list of validation errors, total issue count, counts grouped by severity, and a SwaggerHub UI URL for the scanned API. Use this tool when the user identifies the API by org name, API name, and version and asks to validate, scan, or check the governance or standardization of an existing API.

Toolset: Registry API

Parameters:

• orgName (string) required: The organization name that owns the API and provides the standardization rules (case-sensitive)

• apiName (string) required: API name (case-sensitive)

• version (string) required: Version identifier

Generate and save a new API or a new version of an existing API based on a prompt using SmartBear AI. This tool automatically applies organization governance and standardization rules during API generation. The specType parameter determines the format of the generated definition. Use: 'openapi20' for OpenAPI 2.0, 'openapi30x' for OpenAPI 3.0.x, 'openapi31x' for OpenAPI 3.1.x, 'asyncapi2xx' for AsyncAPI 2.x, 'asyncapi30x' for AsyncAPI 3.0.x. Use this tool when creating APIs that comply with governance policies or when generating APIs from natural language descriptions. Use this tool when users ask to create, generate, or design APIs with governance or standardization requirements. Fails with a conflict error if the API version already exists. Returns API details and SwaggerHub URL.

Toolset: Registry API

Parameters:

• owner (string) required: API owner (organization or user, case-sensitive)

• apiName (string) required: API name

• prompt (string) required: The prompt describing the desired API functionality (e.g., 'Create a RESTful API for managing a pet store with endpoints for pets, orders, and inventory')

• specType (enum): Specification type for the generated API definition. Use: 'openapi20' for OpenAPI 2.0, 'openapi30x' for OpenAPI 3.0.x (default), 'openapi31x' for OpenAPI 3.1.x, 'asyncapi2xx' for AsyncAPI 2.x, 'asyncapi30x' for AsyncAPI 3.0.x (default: "openapi30x")

Standardize and fix an API definition using AI to ensure compliance with governance policies. Scans the API definition for standardization errors and automatically fixes them using SmartBear AI. Optionally provide 'newVersion' (e.g. patch bump '1.0.0' → '1.0.1') to save the fixed definition as a new version — omitting it will overwrite the current version. Returns the number of errors found, the fixed definition, and a URL to view the standardized API. Use this tool when users ask to standardize, fix, govern, or ensure governance compliance of APIs.

Toolset: Registry API

Parameters:

• owner (string) required: API owner (organization or user, case-sensitive)

• api (string) required: API name (case-sensitive)

• version (string) required: Version identifier

• newVersion (string): The version to save the fixed definition as (e.g. '1.0.1'). Omitting this will overwrite the current version — prefer providing a patch bump (e.g. '1.0.0' → '1.0.1') unless the user specifies otherwise.

Apply targeted search/replace edits to a YAML API definition in SwaggerHub Registry. Only OpenAPI and AsyncAPI definitions are supported. Each edit's 'oldString' must be copied exactly from swagger_get_api_definition with format:'text' and without 'resolved' or 'flatten' — those options transform the definition, so edits based on them will not match the stored source. JSON definitions are not supported. Nothing is saved unless every edit applies — failed edits are returned with 'no_match' or 'ambiguous' status. When 'newVersion' is given the patched definition is saved as a new private version; patching in place keeps the visibility of the existing version. Use this tool to fix specific issues in an existing API without regenerating the whole definition.

Toolset: Registry API

Parameters:

• owner (string) required: API owner (organization or user, case-sensitive)

• apiName (string) required: API name (case-sensitive)

• version (string) required: Version of the definition to patch (base version, e.g. '1.0.0')

• newVersion (string): Version to save the patched definition as (e.g. '1.0.1'). Must not already exist and is always created as private. Omit to overwrite the base version, which keeps its current visibility. The definition's info.version is updated automatically — do not add an edit for it.

• edits (array) required: Search/replace edits applied sequentially to the YAML definition. Nothing is saved unless every edit applies (atomic).

Generate Pact tests using PactFlow AI. You can provide one or more of the following input types: (1) request/response pairs for specific interactions, (2) code files to analyze and extract interactions from, and/or (3) OpenAPI document to generate tests for specific endpoints. When providing an OpenAPI document, a matcher is required to specify which endpoints to generate tests for.

Toolset: Generate Pact Tests

Parameters:

• language (enum): Target language for the generated Pact tests. If not provided, will be inferred from other inputs.

• requestResponse (object): Direct request/response pair for a specific interaction. Use this when you have concrete examples of API requests and responses

• code (array): Collection of source code files to analyze and extract API interactions from. Include client code, data models, existing tests, or any code that makes API calls

• openapi (any)

• additionalInstructions (string): Optional free-form instructions to guide the generation process (e.g., 'Focus on error scenarios', 'Include authentication headers', 'Use specific test framework patterns')

• testTemplate (object): Optional test template to use as a basis for generation. Helps ensure generated tests follow your specific patterns, frameworks, and coding standards

Review Pact tests using PactFlow AI. You can provide the following inputs: (1) Pact tests to be reviewed along with metadata

Toolset: Review Pact Tests

Parameters:

• pactTests (object) required: Primary pact tests that needs to be refined.

• code (array): Collection of source code files to analyze and extract API interactions from. Include client code, data models, existing tests, or any code that makes API calls

• userInstructions (string): Optional free-form instructions that provide additional context or specify areas of focus during the refinement process of the Pact test.

• errorMessages (array): Optional error output from failed contract test runs. These can be used to better understand the context or failures observed and guide the recommendations toward resolving specific issues.

• openapi (any)

Retrieve the states of a specific provider

Toolset: Fetch Provider States

Parameters:

• provider (string) required: name of the provider to retrieve states for

• pageNumber (number): Page number (default: 1)

• pageSize (number): Results per page (default: 5)

Performs a comprehensive compatibility check to determine whether a specific version of a service (pacticipant) can be safely deployed into a given environment. It analyzes the complete contract matrix of consumer-provider relationships to confirm that all required integrations are verified and compatible.

Toolset: Can I Deploy

Parameters:

• pacticipant (string) required: The name of the pacticipant (application/service) being evaluated for deployment

• version (string) required: The version of the pacticipant that you want to check if it's safe to deploy

• environment (string) required: The target environment where the pacticipant version will be deployed (e.g., 'production', 'staging', 'test')

Retrieve the comprehensive contract verification matrix that shows the relationship between consumer and provider versions, their associated pact files, and verification results stored in the Pact Broker or Pactflow. The matrix provides detailed visibility into which consumer and provider versions have been successfully verified against each other, and highlights failures with detailed information about the cause.

Toolset: Matrix

Parameters:

• latestby (string): This property removes the rows for the overridden pacts/verifications from the results. The options are cvp (show only the latest row for each consumer version and provider) and cvpv (show only the latest row each consumer version and provider version). For a can-i-deploy query with one selector, it should be set to cvp. For a can-i-deploy query with two selectors, it should be set to cvpv.

• limit (number): The limit on the number of results to return (1-1000, default: 100) (default: 100)

• q (array) required

Use Cases: 1. Quickly identify which consumer and provider version combinations have passed or failed verification. 2. Diagnose and investigate why a particular consumer-provider verification failed. 3. Visualize the overall contract compatibility across two pacticipants / services. 4. Perform advanced queries using selectors to understand compatibility within specific branches, environments, or version ranges. 5. Support informed deployment decisions by answering 'can I deploy version X of this service to production?' 6. Expose contract verification details to non-frequent API users in a more accessible format.

Check your PactFlow AI entitlements and credit balance if you encounter 401 Unauthorized errors or permission/credit issues when using PactFlow AI features.

Toolset: PactFlow AI Status

Use Cases: 1. Diagnose 401 unauthorized errors when attempting to use PactFlow AI features 2. Check remaining AI credits when PactFlow AI operations are rejected due to insufficient credits 3. Verify account entitlements when users receive permission denied errors for PactFlow AI functionality 4. Troubleshoot PactFlow AI access issues by retrieving current entitlement status and credit balance 5. Provide detailed error context when PactFlow AI features are unavailable due to account limitations

Fetch metrics across the entire workspace

Toolset: Metrics

Parameters: None

Fetch metrics for all teams

Toolset: Metrics

Parameters: None

Retrieve all pacticipants (applications/services) registered in the Pact Broker or PactFlow workspace.

Toolset: Pacticipants

Parameters:

• pageNumber (number): Page number (default: 1)

• pageSize (number): Number of results per page (default: 5)

Retrieve details for a specific pacticipant by name.

Toolset: Pacticipants

Parameters:

• pacticipantName (string) required: Name of the pacticipant (application or service)

Retrieve all branches for a given pacticipant, with optional filtering and pagination.

Toolset: Branches and Versions

Parameters:

• pacticipantName (string) required: Name of the pacticipant

• q (string): Filter branches by name

• pageNumber (number): Page number (default: 1)

• pageSize (number): Results per page (default: 5)

Retrieve all versions for a given pacticipant.

Toolset: Branches and Versions

Parameters:

• pacticipantName (string) required: Name of the pacticipant

• pageNumber (number): Page number (default: 1)

• pageSize (number): Results per page (default: 5)

Retrieve details for a specific version of a pacticipant.

Toolset: Branches and Versions

Parameters:

• pacticipantName (string) required: Name of the pacticipant

• versionNumber (string) required: Version number to retrieve

Retrieve the latest version of a pacticipant, optionally filtered by tag.

Toolset: Branches and Versions

Parameters:

• pacticipantName (string) required: Name of the pacticipant

• tag (string): Tag to filter by. If omitted, returns the overall latest version.

Retrieve all environments configured in the Pact Broker or PactFlow workspace.

Toolset: Environments and Deployments

Parameters:

• pageNumber (number): Page number (default: 1)

• pageSize (number): Results per page (default: 5)

Retrieve details for a specific environment by UUID.

Toolset: Environments and Deployments

Parameters:

• environmentId (string) required: UUID of the environment

Record that a version of a pacticipant has been deployed to an environment.

Toolset: Environments and Deployments

Parameters:

• pacticipantName (string) required: Name of the pacticipant that was deployed

• versionNumber (string) required: Version number that was deployed

• environmentId (string) required: UUID of the target environment

• applicationInstance (string): Identifies a specific instance when multiple instances of the same application are deployed to the same environment (e.g. 'blue', 'green')

Retrieve all versions currently deployed to a given environment.

Toolset: Environments and Deployments

Parameters:

• environmentId (string) required: UUID of the environment

• pageNumber (number): Page number (default: 1)

• pageSize (number): Results per page (default: 5)

Record that a version of a pacticipant has been released to an environment (for mobile/library release workflows).

Toolset: Environments and Deployments

Parameters:

• pacticipantName (string) required: Name of the pacticipant that was released

• versionNumber (string) required: Version number that was released

• environmentId (string) required: UUID of the target environment

Retrieve all versions currently released and supported in a given environment.

Toolset: Environments and Deployments

Parameters:

• environmentId (string) required: UUID of the environment

• pageNumber (number): Page number (default: 1)

• pageSize (number): Results per page (default: 5)

Publish one or more consumer Pact contracts to the Pact Broker or PactFlow, with branch and tag metadata.

Toolset: Contracts

Parameters:

• pacticipantName (string) required: Name of the consumer application

• pacticipantVersionNumber (string) required: Version number of the consumer

• contracts (array) required: Contracts to publish

• tags (array): Version tags (e.g. 'main', 'staging')

• branch (string): Branch name of the consumer

• buildUrl (string): URL of the CI build that produced these contracts

Publish a provider OpenAPI or AsyncAPI contract and self-verification results to PactFlow (Bi-Directional Contract Testing).

Toolset: Contracts

Parameters:

• providerName (string) required: Name of the provider application

• pacticipantVersionNumber (string) required: Version number of the provider

• contract (object) required: Provider contract (OpenAPI or AsyncAPI spec) and verification details

• tags (array): Version tags

• branch (string): Branch name of the provider

• buildUrl (string): URL of the CI build

Retrieve the pacts that a provider should verify, based on consumer version selectors and WIP/pending pact configuration.

Toolset: Contracts

Parameters:

• providerName (string) required: Name of the provider to get pacts for

• consumerVersionSelectors (array): Selectors specifying which consumer versions to include

• includePendingStatus (boolean): Include the pending status in the results

• includeWipPactsSince (string): Include WIP pacts published since this date (ISO 8601)

• providerVersionBranch (string): Branch of the provider version being verified

• providerVersionTags (array): Tags for the provider version being verified

Fetch the provider OpenAPI contract for a given provider version in Bi-Directional Contract Testing.

Toolset: Bi-Directional Contract Testing

Parameters:

• providerName (string) required: Name of the provider

• providerVersionNumber (string) required: Provider version number

• pageNumber (number): Page number (default: 1)

• pageSize (number): Results per page (default: 5)

Fetch the self-verification results for a provider contract version in Bi-Directional Contract Testing.

Toolset: Bi-Directional Contract Testing

Parameters:

• providerName (string) required: Name of the provider

• providerVersionNumber (string) required: Provider version number

• pageNumber (number): Page number (default: 1)

• pageSize (number): Results per page (default: 5)

Fetch all consumer Pact contracts relevant to a given provider version in Bi-Directional Contract Testing.

Toolset: Bi-Directional Contract Testing

Parameters:

• providerName (string) required: Name of the provider

• providerVersionNumber (string) required: Provider version number

• pageNumber (number): Page number (default: 1)

• pageSize (number): Results per page (default: 5)

Fetch the consumer contract verification results for a given provider version in Bi-Directional Contract Testing.

Toolset: Bi-Directional Contract Testing

Parameters:

• providerName (string) required: Name of the provider

• providerVersionNumber (string) required: Provider version number

• pageNumber (number): Page number (default: 1)

• pageSize (number): Results per page (default: 5)

Fetch the cross-contract verification results for a given provider version in Bi-Directional Contract Testing.

Toolset: Bi-Directional Contract Testing

Parameters:

• providerName (string) required: Name of the provider

• providerVersionNumber (string) required: Provider version number

• pageNumber (number): Page number (default: 1)

• pageSize (number): Results per page (default: 5)

Fetch the consumer Pact contract for a specific consumer-provider version pair in Bi-Directional Contract Testing.

Toolset: Bi-Directional Contract Testing

Parameters:

• providerName (string) required: Name of the provider

• providerVersionNumber (string) required: Provider version number

• consumerName (string) required: Name of the consumer

• consumerVersionNumber (string) required: Consumer version number

• pageNumber (number): Page number (default: 1)

• pageSize (number): Results per page (default: 5)

Fetch the provider OpenAPI contract for a specific consumer-provider version pair in Bi-Directional Contract Testing.

Toolset: Bi-Directional Contract Testing

Parameters:

• providerName (string) required: Name of the provider

• providerVersionNumber (string) required: Provider version number

• consumerName (string) required: Name of the consumer

• consumerVersionNumber (string) required: Consumer version number

• pageNumber (number): Page number (default: 1)

• pageSize (number): Results per page (default: 5)

Fetch the provider contract self-verification results for a specific consumer-provider version pair in Bi-Directional Contract Testing.

Toolset: Bi-Directional Contract Testing

Parameters:

• providerName (string) required: Name of the provider

• providerVersionNumber (string) required: Provider version number

• consumerName (string) required: Name of the consumer

• consumerVersionNumber (string) required: Consumer version number

• pageNumber (number): Page number (default: 1)

• pageSize (number): Results per page (default: 5)

Fetch the consumer contract verification results for a specific consumer-provider version pair in Bi-Directional Contract Testing.

Toolset: Bi-Directional Contract Testing

Parameters:

• providerName (string) required: Name of the provider

• providerVersionNumber (string) required: Provider version number

• consumerName (string) required: Name of the consumer

• consumerVersionNumber (string) required: Consumer version number

• pageNumber (number): Page number (default: 1)

• pageSize (number): Results per page (default: 5)

Fetch the cross-contract verification results for a specific consumer-provider version pair in Bi-Directional Contract Testing.

Toolset: Bi-Directional Contract Testing

Parameters:

• providerName (string) required: Name of the provider

• providerVersionNumber (string) required: Provider version number

• consumerName (string) required: Name of the consumer

• consumerVersionNumber (string) required: Consumer version number

• pageNumber (number): Page number (default: 1)

• pageSize (number): Results per page (default: 5)

Retrieve all consumer-provider integrations registered in the workspace.

Toolset: Integrations and Network

Parameters:

• pageNumber (number): Page number (default: 1)

• pageSize (number): Results per page (default: 5)

Retrieve the integration network graph for a specific pacticipant.

Toolset: Integrations and Network

Parameters:

• pacticipantName (string) required: Name of the pacticipant to get network for

• pageNumber (number): Page number (default: 1)

• pageSize (number): Results per page (default: 5)

Retrieve all labels used across the workspace.

Toolset: Labels

Parameters:

• pageNumber (number): Page number (default: 1)

• pageSize (number): Results per page (default: 5)

Check whether a specific label is applied to a pacticipant.

Toolset: Labels

Parameters:

• pacticipantName (string) required: Name of the pacticipant

• labelName (string) required: Name of the label

Retrieve all pacticipants that have a specific label applied.

Toolset: Labels

Parameters:

• labelName (string) required: Label name to filter by

• pageNumber (number): Page number (default: 1)

• pageSize (number): Results per page (default: 5)

Fully replace a pacticipant's metadata (display name, main branch, repository URL, etc.).

Toolset: Pacticipants

Parameters:

• pacticipantName (string) required: Name of the pacticipant to update

• displayName (string): Human-readable display name

• mainBranch (string): Name of the main/trunk branch (e.g. 'main')

• repositoryName (string): Repository name

• repositoryNamespace (string): Repository namespace/organisation

• repositoryUrl (string): URL of the source repository

Partially update a pacticipant's metadata — only fields provided are changed.

Toolset: Pacticipants

Parameters:

• pacticipantName (string) required: Name of the pacticipant to update

• displayName (string): Human-readable display name

• mainBranch (string): Name of the main/trunk branch (e.g. 'main')

• repositoryName (string): Repository name

• repositoryNamespace (string): Repository namespace/organisation

• repositoryUrl (string): URL of the source repository

Update metadata for a specific pacticipant version.

Toolset: Branches and Versions

Parameters:

• pacticipantName (string) required: Name of the pacticipant

• versionNumber (string) required: Version number to update

• buildUrl (string): URL of the CI build that produced this version

Retrieve all versions published from a specific branch of a pacticipant.

Toolset: Branches and Versions

Parameters:

• pacticipantName (string) required: Name of the pacticipant

• branchName (string) required: Name of the branch

• pageNumber (number): Page number (default: 1)

• pageSize (number): Results per page (default: 5)

Retrieve deployment records for a specific pacticipant version in a specific environment.

Toolset: Environments and Deployments

Parameters:

• pacticipantName (string) required: Name of the pacticipant

• versionNumber (string) required: Version number

• environmentId (string) required: UUID of the environment

• pageNumber (number): Page number (default: 1)

• pageSize (number): Results per page (default: 5)

Retrieve release records for a specific pacticipant version in a specific environment.

Toolset: Environments and Deployments

Parameters:

• pacticipantName (string) required: Name of the pacticipant

• versionNumber (string) required: Version number

• environmentId (string) required: UUID of the environment

• pageNumber (number): Page number (default: 1)

• pageSize (number): Results per page (default: 5)

Create a new deployment environment in PactFlow.

Toolset: Environments and Deployments

Parameters:

• name (string) required: Unique name for the environment (e.g. 'production', 'staging')

• production (boolean) required: Whether this is a production environment

• displayName (string): Human-readable display name

• teamUuids (array): UUIDs of teams that own this environment

Update an existing environment's metadata.

Toolset: Environments and Deployments

Parameters:

• environmentId (string) required: UUID of the environment to update

• name (string) required: Unique name for the environment

• production (boolean) required: Whether this is a production environment

• displayName (string): Human-readable display name

• teamUuids (array): UUIDs of teams that own this environment

Delete an environment by UUID.

Toolset: Environments and Deployments

Parameters:

• environmentId (string) required: UUID of the environment

Register a new application/service (pacticipant) in the workspace.

Toolset: Pacticipants

Parameters:

• name (string) required: Name of the pacticipant (cannot be changed after creation)

• displayName (string): Human-readable display name

• mainBranch (string): Name of the main/trunk branch (e.g. 'main')

• repositoryName (string): Repository name

• repositoryNamespace (string): Repository namespace/organisation

• repositoryUrl (string): URL of the source repository

Delete a pacticipant and all its associated data.

Toolset: Pacticipants

Parameters:

• pacticipantName (string) required: Name of the pacticipant to delete

Retrieve details for a specific branch of a pacticipant.

Toolset: Branches and Versions

Parameters:

• pacticipantName (string) required: Name of the pacticipant

• branchName (string) required: Name of the branch

Delete a branch from a pacticipant.

Toolset: Branches and Versions

Parameters:

• pacticipantName (string) required: Name of the pacticipant

• branchName (string) required: Name of the branch to delete

Apply a label to a pacticipant.

Toolset: Labels

Parameters:

• pacticipantName (string) required: Name of the pacticipant

• labelName (string) required: Name of the label

Remove a label from a pacticipant.

Toolset: Labels

Parameters:

• pacticipantName (string) required: Name of the pacticipant

• labelName (string) required: Name of the label

Retrieve all consumer-provider integrations belonging to a specific team.

Toolset: Integrations and Network

Parameters:

• teamId (string) required: UUID of the team

• pageNumber (number): Page number (default: 1)

• pageSize (number): Results per page (default: 5)

Delete a specific consumer-provider integration.

Toolset: Integrations and Network

Parameters:

• providerName (string) required: Name of the provider

• consumerName (string) required: Name of the consumer

Delete ALL consumer-provider integrations in the workspace.

Toolset: Integrations and Network

Parameters: None

Retrieve all webhooks configured in the workspace.

Toolset: Webhooks

Parameters:

• pageNumber (number): Page number (default: 1)

• pageSize (number): Results per page (default: 5)

Retrieve details for a specific webhook by UUID.

Toolset: Webhooks

Parameters:

• webhookId (string) required: UUID of the webhook

Create a new webhook to trigger on contract events.

Toolset: Webhooks

Parameters:

• description (string) required: Human-readable description of the webhook

• events (array) required: Events that trigger this webhook

• request (object) required: HTTP request to send when triggered

• consumer (object): Restrict to a specific consumer (omit for all)

• provider (object): Restrict to a specific provider (omit for all)

• enabled (boolean): Whether the webhook is enabled (default: true)

• teamUuid (string): UUID of the owning team (null for global)

Update an existing webhook's configuration.

Toolset: Webhooks

Parameters:

• webhookId (string) required: UUID of the webhook to update

• description (string): Human-readable description

• events (array): Events that trigger this webhook

• request (object): HTTP request to send when triggered

• consumer (object): Restrict to a specific consumer

• provider (object): Restrict to a specific provider

• enabled (boolean): Whether the webhook is enabled

• teamUuid (string): UUID of the owning team

Delete a webhook by UUID.

Toolset: Webhooks

Parameters:

• webhookId (string) required: UUID of the webhook

Trigger a test execution of all matching webhooks without a real event.

Toolset: Webhooks

Parameters: None

Trigger a test execution of a specific webhook.

Toolset: Webhooks

Parameters:

• webhookId (string) required: UUID of the webhook

Retrieve all secrets stored in the workspace.

Toolset: Secrets

Parameters:

• pageNumber (number): Page number (default: 1)

• pageSize (number): Results per page (default: 5)

Retrieve metadata for a specific secret by UUID.

Toolset: Secrets

Parameters:

• secretId (string) required: UUID of the secret

Create a new secret for use in webhook authentication.

Toolset: Secrets

Parameters:

• name (string) required: Name of the secret

• value (string) required: Value of the secret

• description (string): Description of the secret

• teamUuid (string): UUID of the owning team (cannot be changed after creation)

Update an existing secret's name, value, or description.

Toolset: Secrets

Parameters:

• secretId (string) required: UUID of the secret to update

• name (string): New name for the secret

• value (string): New value for the secret

• description (string): New description

Delete a secret by UUID.

Toolset: Secrets

Parameters:

• secretId (string) required: UUID of the secret

Retrieve the profile of the currently authenticated user.

Toolset: User, Tokens and Preferences

Parameters: None

Retrieve API tokens for the current user.

Toolset: User, Tokens and Preferences

Parameters:

• pageNumber (number): Page number (default: 1)

• pageSize (number): Results per page (default: 5)

Regenerate (rotate) an API token by ID.

Toolset: User, Tokens and Preferences

Parameters:

• tokenId (string) required: ID of the token to regenerate

Retrieve the current user's preferences.

Toolset: User, Tokens and Preferences

Parameters: None

Retrieve system-wide preferences.

Toolset: User, Tokens and Preferences

Parameters: None

Retrieve the audit log of events in the workspace.

Toolset: Audit

Parameters:

• since (string): Only include events at or after this ISO 8601 timestamp

• userUuid (string): Filter events by PactFlow user UUID

• type (string): Filter events by type (e.g. 'pact_publication')

• sort (string): Sort order: '+timestamp' (asc, default) or '-timestamp' (desc)

• from (string): Start result set from this audit event UUID (keyset pagination)

• pageNumber (number): Page number (default: 1)

• pageSize (number): Results per page (max 100) (default: 5)

Use Cases: 1. Review recent changes to pacticipants, webhooks, or secrets 2. Investigate who published a specific pact or verification 3. Filter events by user or event type for compliance reporting 4. Track deployment recording activity across environments

List all users in the workspace (admin).

Toolset: Admin

Parameters:

• active (boolean): Filter by active/inactive status

• q (string): Filter by name or email

• userType (number): 0 = regular users, 1 = system accounts

• page (number): Page number (default: 1)

• size (number): Results per page (default: 5)

Retrieve details for a specific user by UUID (admin).

Toolset: Admin

Parameters:

• userId (string) required: UUID of the user

Create a new user account (admin).

Toolset: Admin

Parameters:

• email (string) required: Email address of the new user

• name (string) required: Display name of the new user

• firstName (string): First name

• lastName (string): Last name

• externalIdpId (string): External identity provider ID (for SAML/SSO)

• externalIdpUsername (string): External IdP username (for SAML/SSO)

Update a user's profile or active status (admin).

Toolset: Admin

Parameters:

• userId (string) required: UUID of the user to update

• active (boolean): Whether the user is active

• email (string): New email address

• firstName (string): First name

• lastName (string): Last name

• name (string): Display name

Delete a user account (admin).

Toolset: Admin

Parameters:

• userId (string) required: UUID of the user

Send invitations to new users (admin).

Toolset: Admin

Parameters:

• users (array) required: List of users to invite

Replace all roles assigned to a user (admin).

Toolset: Admin

Parameters:

• userId (string) required: UUID of the user

• roles (array) required: Array of role UUIDs to assign

Add a single role to a user (admin).

Toolset: Admin

Parameters:

• userId (string) required: UUID of the user

• roleId (string) required: UUID of the role

Remove a single role from a user (admin).

Toolset: Admin

Parameters:

• userId (string) required: UUID of the user

• roleId (string) required: UUID of the role

List all teams in the workspace (admin).

Toolset: Admin

Parameters:

• q (string): Filter teams by name

• page (number): Page number (default: 1)

• size (number): Results per page (default: 5)

Retrieve details for a specific team by UUID (admin).

Toolset: Admin

Parameters:

• teamId (string) required: UUID of the team

Create a new team (admin).

Toolset: Admin

Parameters:

• name (string) required: Name of the team

• administratorUuids (array): UUIDs of team administrators

• environmentUuids (array): UUIDs of environments assigned to this team

• pacticipantNames (array): Names of pacticipants assigned to this team

Replace a team's configuration (admin).

Toolset: Admin

Parameters:

• teamId (string) required: UUID of the team to update

• name (string) required: Name of the team

• administratorUuids (array): UUIDs of team administrators

• environmentUuids (array): UUIDs of environments assigned to this team

• pacticipantNames (array): Names of pacticipants assigned to this team

Delete a team (admin).

Toolset: Admin

Parameters:

• teamId (string) required: UUID of the team

List all users in a specific team (admin).

Toolset: Admin

Parameters:

• teamId (string) required: UUID of the team

• pageNumber (number): Page number (default: 1)

• pageSize (number): Results per page (default: 5)

Check if a specific user is a member of a team (admin).

Toolset: Admin

Parameters:

• teamId (string) required: UUID of the team

• userId (string) required: UUID of the user

Replace all members of a team (admin).

Toolset: Admin

Parameters:

• teamId (string) required: UUID of the team

• uuids (array) required: UUIDs of users to set as team members (replaces existing)

Add or remove individual users from a team using JSON Patch (admin).

Toolset: Admin

Parameters:

• teamId (string) required: UUID of the team

• operations (array) required: JSON Patch operations to apply

Remove a specific user from a team (admin).

Toolset: Admin

Parameters:

• teamId (string) required: UUID of the team

• userId (string) required: UUID of the user

List all roles defined in the workspace (admin).

Toolset: Admin

Parameters:

• pageNumber (number): Page number (default: 1)

• pageSize (number): Results per page (default: 5)

Retrieve details for a specific role by UUID (admin).

Toolset: Admin

Parameters:

• roleId (string) required: UUID of the role

Create a new role with specific permissions (admin).

Toolset: Admin

Parameters:

• name (string) required: Name of the role

• permissions (array) required: Permissions granted by this role

• description (string): Description of the role

Update an existing role's name and permissions (admin).

Toolset: Admin

Parameters:

• roleId (string) required: UUID of the role to update

• name (string) required: Name of the role

• permissions (array) required: Permissions granted by this role

• description (string): Description of the role

Delete a role (admin).

Toolset: Admin

Parameters:

• roleId (string) required: UUID of the role

Reset all roles to their factory defaults (admin).

Toolset: Admin

Parameters: None

List all available permission scopes (admin).

Toolset: Admin

Parameters:

• pageNumber (number): Page number (default: 1)

• pageSize (number): Results per page (default: 5)

Create a new system account (admin).

Toolset: Admin

Parameters:

• name (string) required: Name of the system account

Retrieve API tokens for a system account (admin).

Toolset: Admin

Parameters:

• accountId (string) required: UUID of the system account

• pageNumber (number): Page number (default: 1)

• pageSize (number): Results per page (default: 5)

Fetch QMetry projects list including projectID, name, projectKey, isArchived, viewIds and folderPath needed for other operations

Toolset: Projects

Parameters:

• projectKey (string): Project key - unique identifier for the project (default: "default")

• params (object) required

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

• filter (string): Filter criteria as JSON string (default '[]') (default: "[]")

Output Description: JSON object containing list of projects details, including Version, Build Number(if greater than or equal to 1), Project ID, name, Project Key and Date Format

Use Cases: 1. Get project list to check user how many project access to particular apikey 2. Retrieve available fields of each project list including projectID, name, projectKey, isArchived, viewIds and folderPath needed for other operations 3. Validate project access and permissions

Examples:

1. Get list of project available to user

{
  "params": {
    "showArchive": false
  }
}

Expected Output: Project active/non archived list including some important fields like projectID, name, projectKey, isArchived, viewIds and folderPath needed for other operations

2. Get projects with custom pagination

{
  "params": {
    "showArchive": false
  },
  "page": 1,
  "limit": 10,
  "start": 0
}

Expected Output: List of projects with custom pagination settings

3. Get not active/archived projects

{
  "params": {
    "showArchive": true
  }
}

Expected Output: List of all projects including archived ones (showArchive: true sent in payload)

4. Filter projects by name

{
  "filter": "[{\"value\":\"MAC\",\"type\":\"string\",\"field\":\"name\"}]"
}

Expected Output: Filtered list of projects matching the name criteria

5. Filter projects by project key

{
  "filter": "[{\"value\":\"MAC\",\"type\":\"string\",\"field\":\"projectKey\"}]"
}

Expected Output: List of projects filtered by project key (e.g. 'MAC', 'UT', etc.)

Hints: 1. Fetch list of projects available to user 2. Use 'default' project key when user doesn't specify one 3. Use params.showArchive: true/false to get archived/non-archived projects, default is false when not provided 4. Pagination supported for large result sets (start, page, limit parameters) 5. Filter parameter should be a JSON string with filter criteria 6. Common filter fields: 'name' (string), 'projectKey' (string)

Set current QMetry project for your account

Toolset: Projects

Parameters:

• projectKey (string): Project key - unique identifier for the project (default: "default")

Output Description: JSON object containing project configuration details, confirmation of project switch, and available project metadata,including Version, Build Number(if greater than or equal to 1), Project ID, name, Project Key and Date Format

Use Cases: 1. Switch to a specific project before performing test case operations 2. Set project context for batch operations on test cases 3. Configure the default project for the current session 4. Validate access to a specific project before proceeding with operations

Examples:

1. Set default project as active

{
  "projectKey": "default"
}

Expected Output: Project context set to 'default' with confirmation of project details

2. Switch to UT project

{
  "projectKey": "UT"
}

Expected Output: Project context switched to 'UT' project with available configurations

3. Set MAC project as active for test case operations

{
  "projectKey": "MAC"
}

Expected Output: Project context set to 'MAC' with viewIds and folder structure

Hints: 1. Always set the project context before performing test case operations in multi-project environments 2. Use the same project key that you'll use in subsequent test case operations 3. Common project keys include 'default', 'UT', 'MAC', 'VT' - check with your QMetry admin for available projects 4. This operation must be performed before fetching test cases if working with non-default projects 5. The project context persists for the current session until changed again

Fetch QMetry project information including viewId and folderPath needed for other operations

Toolset: Projects

Parameters:

• projectKey (string): Project key - unique identifier for the project (default: "default")

Output Description: JSON object containing project details, viewIds, folderPaths, project configuration, 'dateTimeFormatID' (active date format ID), and 'dateTimeFormatNew' array (each entry: { id, name, unique_value } — use unique_value of the matching entry as the date format pattern for all API date fields).

Use Cases: 1. Get project configuration before fetching test cases 2. Retrieve available viewIds for test case listing 3. Get folderPath information for project navigation 4. Validate project access and permissions

Examples:

1. Get default project info

{}

Expected Output: Project configuration with viewIds, folderPaths, and project details

2. Get specific project info

{
  "projectKey": "MAC"
}

Expected Output: MAC project configuration with available views and folders

Hints: 1. Always call this first when user doesn't provide viewId or folderPath 2. Use 'default' project key when user doesn't specify one 3. Extract viewId from latestViews.TC.viewId for test case operations 4. Use empty string '' as folderPath for root directory 5. DATE FORMAT — IMPORTANT: response contains 'dateTimeFormatID' (number) and 'dateTimeFormatNew' (array). 6. dateTimeFormatID = active format ID for this project. 7. dateTimeFormatNew = [{ id, name, unique_value }] — find entry where id === dateTimeFormatID. 8. unique_value is the authoritative date format pattern using Java/QMetry conventions: 9. yyyy = 4-digit year | MM = 2-digit month (01-12) | dd = 2-digit day | MMM = 3-letter month (Jan/Feb/...) 10. Example mappings: 11. unique_value 'MM-dd-yyyy' → format: 12-25-2024 12. unique_value 'dd-MM-yyyy' → format: 25-12-2024 13. unique_value 'yyyy-MM-dd' → format: 2024-12-25 14. unique_value 'dd-MMM-yyyy' → format: 25-Dec-2024 15. Always use this format when sending date values in any create/update payload. 16. Always parse user-provided dates and reformat them to this pattern before sending to API.

Fetch QMetry releases and cycles from the current project

Toolset: Projects

Parameters:

• projectKey (string): Project key - unique identifier for the project (default: "default")

• showArchive (boolean): Whether to include archived records in the results. When true, returns both active and archived items. When false, returns only active (non-archived) items. Applies to any entity type being fetched (test cases, requirements, releases, cycles, builds, platforms, etc.).

Output Description: JSON object with project hierarchy containing releases and their associated cycles

Use Cases: 1. Fetch associated releases and cycles of current project 2. Fetch available releases and cycles of current project 3. Get release and cycle information for test planning 4. List all releases and cycles in a project 5. Search for specific releases using release name or ID 6. Fetch cycle lists based on release ID 7. Search for specific cycles using cycle name or ID 8. Get project structure for test planning and execution 9. Retrieve release hierarchy for reporting purposes

Examples:

1. Get active releases and cycles (default behavior)

{}

Expected Output: List of active releases and cycles excluding archived ones (showArchive: false sent in payload)

2. Get active/unarchived releases and cycles explicitly

{
  "showArchive": false
}

Expected Output: List of active releases and cycles excluding archived ones (showArchive: false sent in payload)

3. Get not active/archived releases and cycles

{
  "showArchive": true
}

Expected Output: List of all releases and cycles including archived ones (showArchive: true sent in payload)

Hints: 1. Use 'default' project key when user doesn't specify one 2. PAYLOAD SCENARIOS: 3. - No showArchive parameter → payload: {showArchive: false} → Returns only active releases/cycles 4. - showArchive: false → payload: {showArchive: false} → Returns only active/non-archived releases/cycles 5. - showArchive: true → payload: {showArchive: true} → Returns all releases/cycles including archived ones 6. Default behavior always excludes archived items unless explicitly requested 7. Releases contain cycles - use this hierarchy for test execution planning 8. Each release can have multiple cycles representing different testing phases

Fetch QMetry builds from the current project

Toolset: Projects

Parameters:

• projectKey (string): Project key - unique identifier for the project (default: "default")

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

• filter (string): Filter criteria as JSON string (default '[]') (default: "[]")

Output Description: JSON object with builds list and pagination metadata

Use Cases: 1. Fetch all from the current project 2. Fetch all available builds for test execution planning 3. Get build metadata for test run assignments 4. List builds for reporting and analytics 5. Filter builds by name or archive status 6. Get paginated build results for large projects 7. Retrieve build information for CI/CD integration 8. Search for specific builds using filters 9. Get build details for test execution history

Examples:

1. Get all builds (default behavior)

{}

Expected Output: List of all builds with default pagination (10 items per page)

2. Get builds with custom pagination

{
  "page": 1,
  "limit": 10,
  "start": 0
}

Expected Output: List of builds with custom pagination settings

3. Filter builds by name

{
  "filter": "[{\"value\":\"Build 1.0\",\"type\":\"string\",\"field\":\"name\"}]"
}

Expected Output: Filtered list of builds matching the name criteria

4. Filter builds by archive status

{
  "filter": "[{\"value\":[1,0],\"type\":\"list\",\"field\":\"isArchived\"}]"
}

Expected Output: List of builds filtered by archive status (archived and non-archived)

Hints: 1. Use 'default' project key when user doesn't specify one 2. Default pagination: start=0, page=1, limit=10 3. Filter parameter should be a JSON string with filter criteria 4. Common filter fields: 'name' (string), 'isArchived' (list of 0,1) 5. Empty payload {} is sent when no parameters are provided 6. Builds are also known as 'drops' in QMetry terminology 7. Use builds for associating test executions with specific software versions

Fetch QMetry platforms from the current project

Toolset: Projects

Parameters:

• projectKey (string): Project key - unique identifier for the project (default: "default")

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

• sort (string): Sort criteria as JSON string (default '[{"property":"platformID","direction":"DESC"}]') (default: "[{"property":"platformID","direction":"DESC"}]")

• filter (string): Filter criteria as JSON string (default '[]') (default: "[]")

Output Description: JSON object with platforms list and pagination metadata

Use Cases: 1. Fetch all platforms from the current project 2. Get platform metadata for test execution planning 3. List platforms for test environment selection 4. Filter platforms by name or properties 5. Get paginated platform results for large projects 6. Retrieve platform information for cross-platform testing 7. Search for specific platforms using filters 8. Get platform details for test execution assignment

Examples:

1. Get all platforms (default behavior)

{}

Expected Output: List of all platforms with default pagination (10 items per page)

2. Get platforms with custom pagination

{
  "page": 1,
  "limit": 10,
  "start": 0
}

Expected Output: List of platforms with custom pagination settings

3. Filter platforms by name

{
  "filter": "[{\"value\":\"Chrome\",\"type\":\"string\",\"field\":\"name\"}]"
}

Expected Output: Filtered list of platforms matching the name criteria

4. Filter platforms by archive status

{
  "filter": "[{\"value\":[1,0],\"type\":\"list\",\"field\":\"isArchived\"}]"
}

Expected Output: List of platforms filtered by archive status (archived and non-archived)

5. Get only archived platforms

{
  "filter": "[{\"value\":[1],\"type\":\"list\",\"field\":\"isArchived\"}]"
}

Expected Output: List of only archived platforms

6. Get only active/non-archived platforms

{
  "filter": "[{\"value\":[0],\"type\":\"list\",\"field\":\"isArchived\"}]"
}

Expected Output: List of only active/non-archived platforms

7. Get platforms with custom sorting

{
  "sort": "[{\"property\":\"name\",\"direction\":\"ASC\"}]"
}

Expected Output: List of platforms sorted by name in ascending order

Hints: 1. Use 'default' project key when user doesn't specify one 2. Default pagination: start=0, page=1, limit=10 3. Filter parameter should be a JSON string with filter criteria 4. Sort parameter should be a JSON string with sort criteria 5. Default sort: platformID descending 6. Common filter fields: 'name' (string), 'isArchived' (list of 0,1) for archive status 7. IMPORTANT: Always use 'isArchived' field for filtering by archive status, even though response shows 'isPlatformArchived' 8. Archive status values: 0 = active/non-archived, 1 = archived 9. Empty payload {} is sent when no parameters are provided 10. Use platforms for cross-platform testing and environment selection

Create a new release in QMetry with optional cycle for test planning and execution tracking

Toolset: Projects

Parameters:

• projectKey (string): Project key - unique identifier for the project (default: "default")

• release (object) required

• cycle (object): Optional cycle to create within the release

Output Description: JSON object containing the created release ID, release details, and cycle information if provided

Use Cases: 1. Create a new release for a major product version (e.g., v2.0, Q1 Release) 2. Create a release with an initial cycle for immediate test planning 3. Set up release dates for sprint planning and milestone tracking 4. Organize test execution by product versions and cycles 5. Create release hierarchy for better test planning and reporting 6. Establish test execution phases with releases and cycles

Examples:

1. Create a basic release with just a name

{
  "release": {
    "name": "Release 2.0"
  }
}

Expected Output: Release 'Release 2.0' created successfully with generated release ID

2. Create a release with description and dates

{
  "release": {
    "name": "Q1 2024 Release",
    "description": "First quarter release for 2024",
    "startDate": "01-01-2024",
    "targetDate": "31-03-2024"
  }
}

Expected Output: Release 'Q1 2024 Release' created with start date 01-01-2024 and target date 31-03-2024

3. Create a release with an initial cycle

{
  "release": {
    "name": "Release 3.0",
    "description": "Major product update"
  },
  "cycle": {
    "name": "Sprint 1",
    "isLocked": false,
    "isArchived": false
  }
}

Expected Output: Release 'Release 3.0' created with cycle 'Sprint 1' for test execution planning

4. Create a release with all details

{
  "release": {
    "name": "Summer 2024 Release",
    "description": "Summer product release with new features",
    "startDate": "01-06-2024",
    "targetDate": "31-08-2024"
  },
  "cycle": {
    "name": "Beta Testing Cycle",
    "isLocked": false
  }
}

Expected Output: Release 'Summer 2024 Release' created with dates and 'Beta Testing Cycle' for test execution

Hints: 1. CRITICAL: release.name is REQUIRED - must provide a name for the release 2. Date format depends on QMetry instance configuration: DD-MM-YYYY or MM-DD-YYYY 3. Check your QMetry instance settings to determine the correct date format 4. If dates are in wrong format, QMetry will return an error - verify format with admin 5. projectID is optional in the release object - it will be auto-resolved from the project key if not provided 6. To explicitly set projectID, first call FETCH_PROJECT_INFO to get the numeric project ID 7. cycle parameter is completely optional - omit it if you only want to create a release 8. If providing cycle, cycle.name is REQUIRED 9. cycle.isLocked defaults to false if not provided - set to true to prevent modifications 10. cycle.isArchived defaults to false if not provided - set to true to archive immediately (rare) 11. Releases can have multiple cycles added later using other tools 12. Use descriptive release names like 'Release 2.0', 'Q1 2024', 'Sprint 15' for better organization 13. startDate and targetDate help with sprint planning and milestone tracking 14. Creating a release with a cycle is useful for immediate test planning after release creation 15. Release hierarchy: Project → Release → Cycle → Test Execution 16. After creating a release, you can associate test suites and test cases with it 17. Use FETCH_RELEASES_CYCLES tool after creation to verify the release was created successfully

Create a new cycle within an existing release in QMetry for test execution planning

Toolset: Projects

Parameters:

• projectKey (string): Project key - unique identifier for the project (default: "default")

• cycle (object) required

Output Description: JSON object containing the created cycle ID, cycle details, and association with the release

Use Cases: 1. Create a new test cycle for a sprint within an existing release 2. Add additional testing phases to an existing release 3. Set up regression testing cycles for a specific release 4. Organize test execution by sprints, phases, or iterations 5. Create cycles with specific date ranges for milestone tracking 6. Establish test execution phases within release planning

Examples:

1. Create a basic cycle with just a name in a release

{
  "cycle": {
    "name": "Sprint 2",
    "releaseID": 12345
  }
}

Expected Output: Cycle 'Sprint 2' created successfully in release ID 12345

2. Create a cycle with description and dates

{
  "cycle": {
    "name": "Regression Testing Cycle",
    "description": "Full regression testing for release 2.0",
    "startDate": "15-01-2024",
    "targetDate": "31-01-2024",
    "releaseID": 12345
  }
}

Expected Output: Cycle 'Regression Testing Cycle' created with start date 15-01-2024 and target date 31-01-2024 in release 12345

3. Create a locked cycle to prevent modifications

{
  "cycle": {
    "name": "Final QA Cycle",
    "description": "Locked cycle for final QA testing",
    "isLocked": true,
    "isArchived": false,
    "releaseID": 12345
  }
}

Expected Output: Locked cycle 'Final QA Cycle' created in release 12345 to prevent modifications

4. Create a cycle with all details including project ID and dates

{
  "cycle": {
    "name": "Sprint 3 - Feature Testing",
    "description": "Testing new features for Sprint 3",
    "startDate": "01-02-2024",
    "targetDate": "15-02-2024",
    "isLocked": false,
    "isArchived": false,
    "projectID": 67890,
    "releaseID": 12345
  }
}

Expected Output: Cycle 'Sprint 3 - Feature Testing' created with dates and project context in release 12345

Hints: 1. CRITICAL: cycle.releaseID is REQUIRED - must provide the release ID to associate this cycle with 2. CRITICAL: cycle.name is REQUIRED - must provide a name for the cycle 3. HOW TO GET releaseID: 4. 1. Call FETCH_RELEASES_CYCLES tool to get all releases and their IDs 5. 2. From the response, get value from projects.releases[].releaseID 6. 3. Use that numeric releaseID in the cycle.releaseID parameter 7. Example: Release 'Q1 2024' might have releaseID: 12345 8. CRITICAL WORKFLOW - IF USER PROVIDES RELEASE NAME: 9. 1. User says: 'Create cycle Sprint 2 in release Q1 2024' 10. 2. You MUST first call FETCH_RELEASES_CYCLES tool to get all releases 11. 3. Search the response for release with name 'Q1 2024' 12. 4. Extract projects.releases[].releaseID from matching release 13. 5. Use that releaseID in cycle.releaseID parameter 14. 6. If release name not found, inform user and list available releases 15. Example workflow: 16. - User request: 'Create cycle Sprint 2 in Release 2.0' 17. - Step 1: Call FETCH_RELEASES_CYCLES 18. - Step 2: Find release where name = 'Release 2.0', get its releaseID (e.g., 12345) 19. - Step 3: Call CREATE_CYCLE with cycle.releaseID = 12345 20. RELEASE NAME RESOLUTION: 21. - NEVER assume or guess release IDs - always fetch from API 22. - Release names are user-defined strings (e.g., 'Q1 2024', 'Release 2.0', 'Sprint 15') 23. - Release IDs are numeric identifiers assigned by QMetry (e.g., 12345, 67890) 24. - Match release names case-insensitively when searching 25. - If multiple releases match the name, ask user to clarify or use the most recent one 26. - FETCH_RELEASES_CYCLES returns: projects.releases[] array with name and releaseID fields 27. Date format depends on QMetry instance configuration: DD-MM-YYYY or MM-DD-YYYY 28. Check your QMetry instance settings to determine the correct date format 29. If dates are in wrong format, QMetry will return an error - verify format with admin 30. projectID is optional in the cycle object - it will be auto-resolved from the project key if not provided 31. To explicitly set projectID, first call FETCH_PROJECT_INFO to get the numeric project ID 32. cycle.isLocked defaults to false if not provided - set to true to prevent modifications 33. cycle.isArchived defaults to false if not provided - set to true to archive immediately (rare) 34. Use descriptive cycle names like 'Sprint 2', 'Regression Cycle', 'Alpha Testing' for better organization 35. startDate and targetDate help with sprint planning and milestone tracking 36. Cycle hierarchy: Project → Release → Cycle → Test Execution 37. After creating a cycle, you can associate test suites and test cases with it 38. Use FETCH_RELEASES_CYCLES tool after creation to verify the cycle was created successfully 39. DIFFERENCE FROM CREATE_RELEASE: This tool creates a cycle in an EXISTING release, while CREATE_RELEASE can create a release with an optional cycle 40. If you need to create both a release and a cycle together, use CREATE_RELEASE tool instead 41. If release doesn't exist yet, create it first with CREATE_RELEASE, then add more cycles with this tool

Update an existing cycle in QMetry for test execution planning

Toolset: Projects

Parameters:

• projectKey (string): Project key - unique identifier for the project (default: "default")

• cycle (object) required

Output Description: JSON object containing the updated cycle details and confirmation of update

Use Cases: 1. Update cycle name for better organization 2. Modify cycle dates to reflect schedule changes 3. Adjust testing phase timelines within a release 4. Update cycle metadata for sprint tracking 5. Revise milestone dates for test execution planning 6. Rename cycles to match updated sprint naming conventions

Examples:

1. Update cycle name

{
  "cycle": {
    "name": "Alpha_v1_Updated",
    "buildID": 1494,
    "releaseID": 3729
  }
}

Expected Output: Cycle updated successfully with new name 'Alpha_v1_Updated'

2. Update cycle dates

{
  "cycle": {
    "startDate": "10-10-2018",
    "targetDate": "11-11-2018",
    "buildID": 1494,
    "releaseID": 3729
  }
}

Expected Output: Cycle dates updated successfully with new start date 10-10-2018 and target date 11-11-2018

3. Update cycle name and dates together

{
  "cycle": {
    "name": "Sprint 2 - Updated",
    "startDate": "15-01-2024",
    "targetDate": "31-01-2024",
    "buildID": 1494,
    "releaseID": 3729
  }
}

Expected Output: Cycle updated with new name and dates successfully

Hints: 1. CRITICAL: cycle.buildID is REQUIRED - must provide the build ID to identify the cycle to update 2. CRITICAL: cycle.releaseID is REQUIRED - must provide the release ID to identify the cycle to update 3. HOW TO GET buildID and releaseID: 4. 1. Call FETCH_RELEASES_CYCLES tool (API: 'Cycle/List') to get all cycles 5. 2. From the response, get buildID from projects.releases[].builds[].buildID 6. 3. From the response, get releaseID from projects.releases[].releaseID 7. 4. Use those numeric IDs in cycle.buildID and cycle.releaseID parameters 8. Example: Cycle 'Sprint 2' might have buildID: 1494 and releaseID: 3729 9. CRITICAL WORKFLOW - IF USER PROVIDES CYCLE NAME: 10. 1. User says: 'Update cycle Sprint 2 to change dates' 11. 2. You MUST first call FETCH_RELEASES_CYCLES tool to get all cycles 12. 3. Search the response for cycle with matching name 'Sprint 2' 13. 4. Extract buildID and releaseID from the matching cycle 14. 5. Use those IDs in cycle.buildID and cycle.releaseID parameters 15. 6. If cycle name not found, inform user and list available cycles 16. Example workflow: 17. - User request: 'Update cycle Alpha_v1 name to Alpha_v1_Updated' 18. - Step 1: Call FETCH_RELEASES_CYCLES 19. - Step 2: Find cycle where name = 'Alpha_v1', get its buildID (e.g., 1494) and releaseID (e.g., 3729) 20. - Step 3: Call UPDATE_CYCLE with cycle.buildID = 1494 and cycle.releaseID = 3729 21. CYCLE IDENTIFICATION: 22. - NEVER assume or guess buildID or releaseID - always fetch from API 23. - Cycle names are user-defined strings (e.g., 'Sprint 2', 'Alpha_v1', 'Regression Cycle') 24. - buildID and releaseID are numeric identifiers assigned by QMetry 25. - Match cycle names case-insensitively when searching 26. - If multiple cycles match the name, ask user to clarify or use the most recent one 27. - FETCH_RELEASES_CYCLES returns: projects.releases[].builds[] array with name, buildID, and releaseID 28. Date format depends on QMetry instance configuration: DD-MM-YYYY or MM-DD-YYYY 29. Check your QMetry instance settings to determine the correct date format 30. NOTE: To verify/update the Date Format - Go to QMetry -> User Profile 31. If dates are in wrong format, QMetry will return an error - verify format with admin 32. You can update name, startDate, or targetDate independently or together 33. Only include the fields you want to update - other fields will remain unchanged 34. startDate and targetDate help with sprint planning and milestone tracking 35. Cycle hierarchy: Project → Release → Cycle → Test Execution 36. After updating a cycle, you can verify changes using FETCH_RELEASES_CYCLES tool 37. DIFFERENCE FROM CREATE_CYCLE: This tool updates an EXISTING cycle, while CREATE_CYCLE creates a new one

Create a new test case in QMetry with steps, metadata, and release/cycle mapping.

Toolset: Test Cases

Parameters:

• tcFolderID (string): Test Case folder ID - SYSTEM AUTOMATICALLY RESOLVES THIS. Leave empty unless you have a specific folder ID. System will fetch project info using the projectKey and extract rootFolders.TC.id automatically. Manual folder ID only needed if you want to target a specific sub-folder.

• skipSteps (boolean): Set to true ONLY when the user explicitly says they do NOT want steps created (e.g. 'create test case without steps', 'no steps', 'skip steps'). When true, the 'steps' field must be omitted entirely. When false or absent (the default), steps MUST always be included — auto-generate them from context if the user did not provide them.

• steps (array): STEPS RULE — include this field unless the user explicitly says NOT to create steps.

NEVER send steps: [] (empty array) — always send at least 1 valid step object. Omit this field entirely (and set skipSteps: true) ONLY when the user explicitly asks to skip steps.

HOW TO POPULATE:

• If user explicitly provides steps: parse each step into { orderId, description, inputData?, expectedOutcome? }.

• If user does NOT provide steps (and did not say to skip them): auto-generate meaningful steps based on the test case name, description, and context. Use your knowledge to infer 2-5 logical, realistic steps for the feature or flow being tested. Example: name='Login Test Case' → [{orderId:1, description:'Navigate to login page'}, {orderId:2, description:'Enter credentials'}, {orderId:3, description:'Submit and verify success'}]

• If user explicitly said NOT to create steps: omit this field and set skipSteps: true.

STEP DEFAULT VALUES: After building the steps array, check 'stepDefaultValues' from Fetch UDF Layout. stepDefaultValues shape: { fieldName: defaultValue } For each step: for each key in stepDefaultValues, if the user did NOT explicitly provide a value for that field → add it to step.UDF with the default value. Auto-apply silently — do NOT ask the user.

Step object fields: orderId (required): sequential integer starting at 1 description (required): step action text inputData (optional): test data for this step expectedOutcome (optional): what should happen after this step UDF (optional): step-level custom fields — auto-fill defaults from stepDefaultValues tcStepID (omit on create — only used when updating existing steps)

• name (string) required

• priority (number)

• component (array)

• testcaseOwner (number)

• testCaseState (number)

• testCaseType (number)

• estimatedTime (number): Estimated execution time in SECONDS (e.g. 3600 = 1 hour, 36000 = 10 hours). NOT minutes.

• testingType (number)

• description (string)

• associateRelCyc (boolean)

• releaseCycleMapping (array): Release/cycle mapping. Set associateRelCyc=true when providing this. version field defaults to 1 if not specified.

• udfFields (record<string, union>): Flat UDF field values. Keys = UDF field names from 'Fetch UDF Layout'. Values depend on fieldTypeName: STRING/LARGETEXT: string, NUMBER: number, DATETIMEPICKER: date string ('14-08-2026'), LOOKUPLIST: numeric ID, MULTILOOKUPLIST: array of IDs [101, 102], CASCADINGLIST: { parent: 101, child: 102 }. Call 'Fetch UDF Layout' with entityType + pageName='ADD' to discover available fields and list option IDs.

Output Description: JSON object containing the new test case ID, summary, and creation metadata.

Use Cases: 1. Create a basic test case with just a name and folder 2. Add detailed steps with custom fields (UDFs) to a test case 3. Associate test case with specific release/cycle for planning 4. Set priority, owner, component, and other metadata using valid IDs from project info 5. Create test cases for automation or manual testing types 6. Add test case to a specific folder using tcFolderID 7. Include estimated execution time and description 8. Map test case to multiple cycles/releases

Examples:

1. MOST COMMON: User provides only a name — steps are auto-generated from context.

{
  "name": "Login Test Case",
  "steps": [
    {
      "orderId": 1,
      "description": "Navigate to the login page"
    },
    {
      "orderId": 2,
      "description": "Enter valid username and password"
    },
    {
      "orderId": 3,
      "description": "Click the Login button"
    },
    {
      "orderId": 4,
      "description": "Verify successful login and dashboard is shown"
    }
  ]
}

Expected Output: Test case created with auto-generated steps inferred from the test case name 'Login Test Case'.

2. Create test case with metadata only — steps auto-generated from context

{
  "tcFolderID": "102653",
  "name": "Login Test Case",
  "priority": 2025268,
  "testCaseState": 2025271,
  "estimatedTime": 3600,
  "description": "Verifies login flow",
  "steps": [
    {
      "orderId": 1,
      "description": "Navigate to the login page"
    },
    {
      "orderId": 2,
      "description": "Enter valid credentials"
    },
    {
      "orderId": 3,
      "description": "Submit the login form"
    },
    {
      "orderId": 4,
      "description": "Verify redirection to the home page"
    }
  ]
}

Expected Output: Test case created with metadata and auto-generated steps based on description 'Verifies login flow'.

3. SCENARIO 1: User explicitly asked for steps — 'create test case with step 1 - Go to login page, step 2 - enter credentials'

{
  "tcFolderID": "102653",
  "name": "Login Flow Test",
  "steps": [
    {
      "orderId": 1,
      "description": "Go to login page"
    },
    {
      "orderId": 2,
      "description": "Enter credentials"
    }
  ]
}

Expected Output: Test case created with 2 steps because user explicitly mentioned steps in prompt.

4. SCENARIO 1: User provided steps with full metadata (steps explicitly mentioned in prompt)

{
  "tcFolderID": "102653",
  "name": "Test Case 1",
  "steps": [
    {
      "orderId": 1,
      "description": "First Step",
      "inputData": "First Data",
      "expectedOutcome": "First Outcome",
      "UDF": {
        "customField1": "Custom Field Data A",
        "customField2": "Custom Field Data B"
      }
    }
  ],
  "priority": 2025268,
  "component": [
    2025328
  ],
  "testcaseOwner": 1467,
  "testCaseState": 2025271,
  "testCaseType": 2025282,
  "estimatedTime": 10,
  "description": "Description",
  "testingType": 2025275,
  "associateRelCyc": true,
  "releaseCycleMapping": [
    {
      "release": 14239,
      "cycle": [
        21395
      ],
      "version": 1
    }
  ]
}

Expected Output: Test case created with steps because user explicitly requested steps. All metadata populated.

5. SCENARIO 3: User explicitly says no steps — 'create a test case without any steps'

{
  "name": "Login Test Case",
  "skipSteps": true
}

Expected Output: Test case created with no steps because user explicitly asked to skip them.

6. User provides name only — steps auto-generated from test case name context

{
  "name": "Password Reset Test Case",
  "steps": [
    {
      "orderId": 1,
      "description": "Navigate to the login page"
    },
    {
      "orderId": 2,
      "description": "Click on 'Forgot Password' link"
    },
    {
      "orderId": 3,
      "description": "Enter registered email address and submit the reset form"
    },
    {
      "orderId": 4,
      "description": "Click reset link from email and set a new password"
    },
    {
      "orderId": 5,
      "description": "Verify login succeeds with the new password"
    }
  ]
}

Expected Output: Test case created with 5 auto-generated steps inferred from the name 'Password Reset Test Case'. No user-provided steps — LLM generated them from context.

Hints: 1. ╔══════════════════════════════════════════════════════════════════════════════╗ 2. ║ STEPS RULE — INCLUDE STEPS UNLESS USER EXPLICITLY ASKS TO SKIP THEM ║ 3. ╚══════════════════════════════════════════════════════════════════════════════╝ 4. 5. Include 'steps' in the payload unless the user explicitly says NOT to create steps. 6. NEVER send steps: [] (empty array) — either send at least 1 valid step object or omit steps with skipSteps: true. 7. 8. HOW TO POPULATE STEPS: 9. 10. SCENARIO 1 — User explicitly provides steps in their prompt. 11. Trigger phrases: 'with steps', 'step 1 -', 'add steps', 'include steps', 'following steps', 'these steps'. 12. Action: Parse the user's step text into { orderId, description, inputData?, expectedOutcome? } objects. 13. Example: 'create test case, step 1 - open browser, step 2 - click login' 14. → steps: [{ orderId: 1, description: 'open browser' }, { orderId: 2, description: 'click login' }] 15. 16. SCENARIO 2 — User does NOT mention steps at all. 17. Action: Generate meaningful steps based on the test case name, description, and all other context provided. 18. Use your knowledge of the feature/flow being tested to infer logical, realistic test steps. 19. Always include 2-5 steps that make sense for the test case. 20. Example: name='Login Test Case' → steps: [{orderId:1, description:'Navigate to login page'}, {orderId:2, description:'Enter credentials'}, {orderId:3, description:'Submit form'}, {orderId:4, description:'Verify login success'}] 21. 22. SCENARIO 3 — User explicitly says NOT to create steps. 23. Trigger phrases: 'no steps', 'without steps', 'skip steps', 'don't add steps', 'without any steps'. 24. Action: Set skipSteps: true and omit the 'steps' field entirely from the payload. 25. Example: 'create test case Login Test Case without steps' → { name: 'Login Test Case', skipSteps: true } 26. 27. STEP DEFAULT VALUES — apply after step generation (scenarios 1 and 2 only): 28. After building the steps array (from user input OR auto-generated), check 'stepDefaultValues' from Fetch UDF Layout. 29. stepDefaultValues shape: { fieldName: defaultValue } — e.g. { 'lookup19': 5232630 } 30. For EACH step, for EACH key in stepDefaultValues: 31. IF the user has NOT explicitly specified a value for that field in the step → set it to the default value. 32. This applies to step UDF fields (step.UDF) that have defaults configured. 33. Auto-apply silently — do NOT ask the user. 34. Example: stepDefaultValues = { status: 5232630 } → every step's UDF.status = 5232630 unless user gave a different value. 35. 36. DECISION TABLE: 37. | Situation | Action | 38. |------------------------------------|-----------------------------------------------------------------------------| 39. | User provided steps | Use steps from user's prompt; fill step UDF defaults from stepDefaultValues | 40. | User did not mention steps | Auto-generate steps from context; fill step UDF defaults from stepDefaultValues | 41. | User explicitly said NO steps | Set skipSteps: true, omit 'steps' field entirely | 42. 43. ╚══════════════════════════════════════════════════════════════════════════════╝ 44. 45. ╔══════════════════════════════════════════════════════════════════╗ 46. ║ STEP 0 — NON-NEGOTIABLE: Call 'Fetch UDF Layout' BEFORE create ║ 47. ╚══════════════════════════════════════════════════════════════════╝ 48. NEVER call 'Create Test Case' without first calling 'Fetch UDF Layout' with entityType='TC', pageName='ADD'. 49. Skipping this step WILL cause 400 errors (CO.MANDATORY_FIELDS_MISSING) because mandatory fields and defaults are unknown. 50. This rule has NO exceptions — not even when the user only provided a name and nothing else. 51. 52. === MANDATORY PRE-CREATE CHECK === 53. 54. SYSTEM FIELDS mandatory check — use 'systemFields' array from Fetch UDF Layout: 55. Each entry: { name, label, fieldTypeName, isMandatory } 56. isMandatory=true (allowBlank=false in QMetry) means the field MUST have a value. 57. IMPORTANT: QMetry's API sometimes returns 'systemFields: []' (empty) even when system fields ARE mandatory. 58. If 'systemFields' is empty, treat the following as always mandatory: name (Summary), testCaseState (Status). 59. For testCaseState default: check 'customListObjs.testCaseState' from Fetch Project Info — use first non-archived entry as fallback. 60. 61. UDF FIELDS mandatory check — use 'fields' array from Fetch UDF Layout: 62. Each entry: { name, label, fieldTypeName, isMandatory, listName? } 63. IMPORTANT: QMetry's API sometimes returns isMandatory=false for fields that ARE enforced as mandatory. 64. The 'isMandatory' flag is a hint, not a guarantee. Trust the actual API error over this flag. 65. When isMandatory=true: field MUST have a value. 66. 67. DEFAULT VALUES — use 'defaultValues' object from Fetch UDF Layout: 68. Shape: { fieldName: defaultValueId } e.g. { 'lookup19': 5232630, 'estimatedTime': 18305.0, 'priority': 5232497 } 69. These are pre-configured QMetry defaults. ALWAYS auto-apply them — even when user did not mention the field. 70. IMPORTANT: QMetry's API sometimes returns 'defaultValues: {}' (empty) even when defaults exist in QMetry settings. 71. If 'defaultValues' is empty, you cannot auto-apply — ask user for mandatory fields without defaults. 72. RULE: if isMandatory=true AND defaultValues[field.name] exists → use default, do NOT ask user. 73. RULE: if isMandatory=true AND NO defaultValues[field.name] → MUST ask user before creating. 74. RULE: if isMandatory=false AND defaultValues[field.name] exists → auto-apply default if user didn't specify. 75. RULE: if isMandatory=false AND no default → skip if user didn't provide. 76. 77. ╔══════════════════════════════════════════════════════════════════════════╗ 78. ║ PRE-FLIGHT DEFAULT SWEEP — MANDATORY STEP BEFORE EVERY CREATE CALL ║ 79. ╚══════════════════════════════════════════════════════════════════════════╝ 80. After resolving mandatory fields, do a full sweep of ALL defaultValues entries: 81. For EACH key in defaultValues: 82. IF the user did not explicitly provide that field → add it to the payload using the default value. 83. This applies regardless of isMandatory — non-mandatory defaults MUST also be auto-applied. 84. Example: defaultValues = { lookup19: 5232630, estimatedTime: 18305, priority: 5232497 } 85. → user only said 'create a test case named X' 86. → payload MUST include: lookup19=5232630, estimatedTime=18305, priority=5232497 87. → WRONG to omit priority/estimatedTime just because they are not mandatory — they have defaults. 88. Skipping this sweep = missing fields in the created record = user-visible data loss. 89. ╚══════════════════════════════════════════════════════════════════════════╝ 90. 91. TEST CASE STEPS — always required (see STEPS RULE above): 92. stepSystemFields: built-in step fields { name, label, fieldTypeName, isMandatory } 93. stepFields: step-level UDF fields { name, label, fieldTypeName, isMandatory, listName? } 94. Mandatory stepFields UDFs (isMandatory=true) must be filled in step.UDF — use stepDefaultValues for defaults, else a placeholder value. 95. STEP DEFAULT VALUES: use 'stepDefaultValues' object from Fetch UDF Layout — same auto-fill logic as defaultValues. 96. For EACH key in stepDefaultValues: if user has NOT explicitly provided a value for that step field → auto-apply the default silently. 97. This applies to all steps (both user-provided and auto-generated). 98. 99. DECISION MATRIX: 100. | isMandatory | Has default | Action | 101. |-------------|-------------|-------------------------------------| 102. | true | YES | Auto-fill with default, no ask | 103. | true | NO | Ask user before creating | 104. | false | YES | Auto-fill with default — REQUIRED | 105. | false | NO | Skip if user didn't provide | 106. 107. Only after ALL mandatory fields are resolved AND default sweep is complete → proceed with create. 108. === END MANDATORY PRE-CREATE CHECK === 109. 110. === ERROR RECOVERY: CO.MANDATORY_FIELDS_MISSING === 111. If create fails with error code 'CO.MANDATORY_FIELDS_MISSING', DO NOT give up. Auto-recover: 112. 1. Parse the 'MISSING_FIELDS' list from the error response (comma-separated field labels). 113. 2. Match each label against 'fields[].label' and 'systemFields[].label' from the Fetch UDF Layout response. 114. 3. For matched UDF fields: check 'listOptions[field.listName]' for valid option IDs. 115. 4. For matched system fields (e.g. 'Status'): check 'customListObjs.testCaseState' from project info. 116. 5. If the field has a 'defaultValues' entry: auto-fill it silently. 117. 6. If no default exists: ask the user ONLY for the missing fields by label. 118. 7. Retry create with the resolved values added to the payload. 119. NEVER ask user to 'try again' manually — resolve and retry automatically. 120. === END ERROR RECOVERY === 121. 122. === DATE FORMAT CHECK (MANDATORY — EVERY CREATE REQUEST) === 123. ALWAYS call 'Fetch QMetry Project Info' before every create request — not only when the user explicitly mentions a date. 124. Any UDF field could be a DATETIMEPICKER. Wrong format causes QMetry to silently discard the field value (API returns success but value is NOT stored — no error). 125. Project info response contains 'dateTimeFormatID' and 'dateTimeFormatNew' array. 126. STEP 1: From project info, read dateTimeFormatID (e.g. 3). 127. STEP 2: Find entry in dateTimeFormatNew where id === dateTimeFormatID → read its unique_value (e.g. 'yyyy-MM-dd'). 128. STEP 3: unique_value is the Java/QMetry format pattern. Mapping: 129. yyyy = 4-digit year | MM = 2-digit month (01-12) | dd = 2-digit day | MMM = 3-letter month (Jan/Feb/...) 130. Example: id=1 → MM-dd-yyyy → '10-25-2000' | id=2 → dd-MM-yyyy → '25-10-2000' | id=3 → yyyy-MM-dd → '2000-10-25' | id=4 → dd-MMM-yyyy → '25-Oct-2000' 131. STEP 4: For EVERY DATETIMEPICKER field in the payload (user-provided OR from defaultValues): 132. - Parse the date regardless of what format the user typed 133. - Re-format it using the active unique_value pattern 134. - Send the re-formatted string to the API 135. Examples with unique_value='yyyy-MM-dd': 136. User says '25 Dec 2024' → send '2024-12-25' 137. User says '12/25/2024' → send '2024-12-25' 138. Default value is a date string '2024-12-25' → already correct, keep it 139. NEVER send a date in a format different from the project's active dateTimeFormatID format. 140. Fetch project info ONCE per create/update operation and reuse dateTimeFormatID for all date fields. 141. === END DATE FORMAT CHECK === 142. 143. If tcFolderID is not provided, it will be auto-resolved to the root test case folder using project info (rootFolders.TC.id). 144. To get valid values for priority, owner, component, etc., call the project info tool and use the returned customListObjs IDs. 145. STALE / NOT-FOUND ID RECOVERY (applies to ALL system fields — priority, component/label, owner, status, testCaseType, testingType, release, cycle): If the user references a value by name and it is NOT found in your current cached project info data, DO NOT give up or skip the field immediately. Instead: call 'Fetch QMetry Project Info' fresh (no arguments needed) to get the latest snapshot, then re-scan the relevant customListObjs list. This is mandatory when: (a) the user just added a new label/priority/status/user in QMetry UI, or (b) the cached info is from an earlier turn. Only skip + show a friendly message if the value is still missing AFTER the fresh fetch. 146. FOLDER ID RESOLUTION (tcFolderID): Project info only exposes the ROOT folder ID (rootFolders.TC.id). Sub-folder IDs are NOT returned by project info. If the user specifies a sub-folder (e.g. 'Folder 1'), use this resolution order: 1. Check if the user already provided the numeric folder ID — use it directly. 2. Try fetching test cases with folderPath='' and scope='folder' — if a TC exists there, its folder context confirms the path, but the ID is still needed from the UI. 3. If still unresolved, ask the user: 'Please provide the numeric folder ID for "". You can find it in the QMetry URL when browsing that folder (look for folderId=XXXXX).' NEVER silently fall back to root folder when the user explicitly named a sub-folder — always ask first. 147. If the user provides a priority name (e.g. 'Blocker'), fetch project info, find the matching priority in customListObjs.priority[index].name, and use its ID in the payload. If the name is not found after a fresh fetch, skip the priority field (it is not required) and show a user-friendly message: 'Test case created without priority, as given priority is not available in the current project.' 148. If the user provides a component name, fetch project info, find the matching component in customListObjs.component[index].name, and use its ID in the payload. If the name is not found, skip the component field (it is not required) and show a user-friendly message: 'Test case created without component, as given component is not available in the current project.' 149. If the user provides an owner name, fetch project info, find the matching owner in customListObjs.owner[index].name, and use its ID in the payload as testcaseOwner. If the name is not found, skip the testcaseOwner field (it is not required) and show a user-friendly message: 'Test case created without owner, as given owner is not available in the current project.' 150. If the user provides a test case state name, fetch project info, find the matching state in customListObjs.testCaseState[index].name, and use its ID in the payload as testCaseState. If the name is not found, skip the testCaseState field (it is not required) and show a user-friendly message: 'Test case created without test case state, as given state is not available in the current project.' 151. If the user provides a test case type name, fetch project info, find the matching type in customListObjs.testCaseType[index].name, and use its ID in the payload as testCaseType. If the name is not found, skip the testCaseType field (it is not required) and show a user-friendly message: 'Test case created without test case type, as given type is not available in the current project.' 152. If the user provides a testing type name, fetch project info, find the matching type in customListObjs.testingType[index].name, and use its ID in the payload as testingType. If the name is not found, skip the testingType field (it is not required) and show a user-friendly message: 'Test case created without testing type, as given testing type is not available in the current project.' 153. Example: If user says 'Create test case with title "High priority test case" and set priority to "Blocker"', first call project info, map 'Blocker' to its ID, and use that ID for the priority field in the create payload. If user says 'set priority to "Urgent"' and 'Urgent' is not found, skip the priority field and show: 'Test case created without priority, as given priority is not available in the current project.' 154. tcFolderID is required; use the root folder ID from project info or a specific folder. 155. STEPS: ALWAYS include steps in the payload. If user did not provide steps, auto-generate them from the test case name and context. See STEPS RULE at top of hints. 156. If the user provides a prompt like 'create test case with steps as step 1 - Go to login page, step 2 - give credential, step 3 - go to test case page, step 4 - create test case', LLM should parse each step and convert it into the steps payload array, mapping each step to an object with orderId, description, and optionally inputData and expectedOutcome. 157. Example mapping: 'step 1 - Go to login page' → { orderId: 1, description: 'Go to login page' }. 158. LLM should increment orderId for each step, use the step text as description, and optionally infer inputData/expectedOutcome if provided in the prompt. 159. Demo steps payload: steps: [ { orderId: 1, description: 'First Step', inputData: 'First Data', expectedOutcome: 'First Outcome', UDF: { customField1: 'Custom Field Data A', customField2: 'Custom Field Data B' } }, ... ] 160. UDF fields in steps must match your QMetry custom field configuration. 161. Release/cycle mapping is optional but useful for planning. 162. If the user wants to link or associate a release and cycle to the test case, set associateRelCyc: true in the payload. 163. If the user provides a release ID, map it from projects.releases[index].releaseID in the project info response, and use that ID in releaseCycleMapping. 164. If the user provides both release and cycle IDs, validate both against the current project's releases and cycles; if valid, use them in releaseCycleMapping. 165. When adding releaseCycleMapping, always include the 'version' field (usually set to 1) in each mapping object. The correct format is: { release: , cycle: [], version: 1 }. If 'version' is missing, the request will fail. 166. If the user provides a release name, map it to its ID from project info; if a cycle name is provided, map it to its ID from the associated release's builds list. 167. Example payload: releaseCycleMapping: [ { release: , cycle: [], version: 1 } ] 168. LLM should ensure that provided release/cycle names or IDs exist in the current project before using them in the payload. If not found, skip and show a user-friendly message: 'Test case created without release/cycle association, as given release/cycle is not available in the current project.' 169. All IDs (priority, owner, etc.) must be valid for your QMetry instance. 170. If a custom field is mandatory, include it in the UDF object. 171. estimatedTime is in SECONDS (e.g. 3600 = 1 hour, 36000 = 10 hours). NOT minutes. 172. Description and testingType are optional but recommended for clarity. 173. 174. UDF (User Defined Fields) WORKFLOW FOR CREATE: 175. 1. Call 'Fetch UDF Layout' with entityType='TC', pageName='ADD' to discover field names, types, list option IDs, and udfmID (projectUserFieldID). 176. IF listOptions[field.listName] is empty after Fetch UDF Layout, the tool already tried a metadata fallback. If STILL empty, ask the user to provide the option ID from the QMetry UI — do NOT guess numeric IDs. 177. 2. For LOOKUPLIST fields: pick one ID from listOptions[field.listName][].id. 178. 3. For MULTILOOKUPLIST fields: pick an array of IDs from listOptions[field.listName][].id. 179. 4. For CASCADINGLIST fields (ROOT-LEVEL UDF — MANDATORY STEPS): 180. a. MUST call 'Fetch Cascade Child Values' with parentId to get available child options (do NOT skip this step). 181. b. Pass the cascade value as: { parent: parentId, child: childId } in udfFields. 182. Example: udfFields: { project19: { parent: 5232623, child: 5232625 } } 183. 5. For STRING/LARGETEXT/NUMBER/DATETIMEPICKER: pass value directly. 184. 6. Pass all UDF values via 'udfFields' param: { fieldName: value }. 185. 7. Mandatory UDF fields (isMandatory=true) MUST be included or create will fail. 186. 187. STEP UDFs: Pass step UDF values in each step's 'UDF' object. 188. Call 'Fetch UDF Layout' for stepFields to discover field names, types, and udfmID (projectUserFieldID). 189. Step UDF field types follow same rules as root UDF EXCEPT for CASCADINGLIST — step cascade requires a DIFFERENT format: 190. 191. STEP CASCADINGLIST UDF FORMAT (critical — different from root cascade): 192. For a cascade field named 'project19' with udfmID=2637584, parent={id:5232626, value:'React'}, child={id:5232628, value:'Redux'}: 193. You MUST include THREE keys inside the step's UDF object: 194. 1. fieldName: { parent: parentId, child: childId } 195. e.g. project19: { parent: 5232626, child: 5232628 } 196. 2. fieldName_value: [{ FieldID: 'fieldName', FieldValue: [{ id: parentId, value: 'parentLabel', child: { id: childId, value: 'childLabel' } }], type: 'CASCADINGLIST' }] 197. e.g. project19_value: [{ FieldID: 'project19', FieldValue: [{ id: 5232626, value: 'React', child: { id: 5232628, value: 'Redux' } }], type: 'CASCADINGLIST' }] 198. 3. fieldName_selectedList: { id: udfmID, name: 'fieldName', type: 'CASCADINGLIST' } 199. e.g. project19_selectedList: { id: 2637584, name: 'project19', type: 'CASCADINGLIST' } 200. To get parentLabel and childLabel: call 'Fetch Cascade Child Values' — it returns option labels alongside IDs. 201. udfmID comes from Fetch UDF Layout stepFields[].projectUserFieldID. 202. NEVER omit _value or _selectedList for step cascade fields — the API silently ignores cascade data without them.

Update an existing QMetry test case OR create a new version by tcID and tcVersionID, with auto-resolution from entityKey.

Toolset: Test Cases

Parameters:

• projectKey (string): Project key - unique identifier for the project (default: "default")

• tcID (number) required: Test Case numeric ID. CRITICAL: the parameter name is 'tcID' — do NOT use 'testCaseId', 'testCaseID', 'tcId', or other variants. Accepts a string or number. This is the internal numeric identifier, not the entity key like 'MAC-TC-1684'. You can get this ID from test case search results or by using filters.

• tcVersionID (number) required: Test Case version number. This is the internal numeric identifier for the version.

• tcVersion (number): Test Case version number (required when withVersion=true for creating new version). This is the current version number from which a new version will be created.

• withVersion (boolean): Pass 'true' if you want to create a new version of the test case with incremented version number. When true, a new version is created (e.g., if current version is 2, new version 3 is created). When false or omitted, updates the existing version specified by tcVersionID. IMPORTANT: Always send proper tcVersionID to identify which version the request is for.

• versionComment (string): Comment or description for the new version (used only when withVersion=true). Helps track what changed in this new version. Example: 'Updated test steps for new requirements'

• notruncurrent (boolean): Flag to control execution behavior for current version when creating a new version. Used in conjunction with withVersion=true.

• notrunall (boolean): Flag to control execution behavior for all versions when creating a new version. Used in conjunction with withVersion=true.

• folderPath (string): Folder path for test suites - SYSTEM AUTOMATICALLY SETS TO ROOT. Leave empty unless you want specific folder. System will automatically use empty string "" (root directory). Only specify if user wants specific folder like "Automation/Regression". (default: "")

• scope (string): Scope of the operation - defines the context for data retrieval. Common values: 'project' (default), 'folder', 'release', 'cycle'. Applies to any entity type being fetched or operated upon. (default: "project")

• isStepUpdated (boolean): Set to true when steps are being added, updated, or removed. Required when including 'steps' or 'removeSteps' arrays.

• steps (array)

• removeSteps (array)

• name (string)

• priority (number)

• component (array)

• owner (number)

• testCaseState (number)

• testCaseType (number)

• estimatedTime (number): Estimated execution time in seconds. Example: 7200 for 2 hours

• executionMinutes (number)

• testingType (number)

• description (string)

• updateOnlyMetadata (boolean): Set to true to update only metadata fields without touching test steps. When true, steps and removeSteps are ignored.

• udfFields (record<string, union>): Flat UDF field values. Keys = UDF field names from 'Fetch UDF Layout'. Values depend on fieldTypeName: STRING/LARGETEXT: string, NUMBER: number, DATETIMEPICKER: date string ('14-08-2026'), LOOKUPLIST: numeric ID, MULTILOOKUPLIST: array of IDs [101, 102], CASCADINGLIST: { parent: 101, child: 102 }. Call 'Fetch UDF Layout' with entityType + pageName='ADD' to discover available fields and list option IDs.

• UDF (record<string, object>): UDF wrapper required for update operations. Keys = UDF field names. Each value must include fieldID (from 'Fetch UDF Layout' with pageName='DETAIL') and value. Also set matching flat key in udfFields for the LOOKUPLIST Alias display. Example: { custom_text: { fieldID: 1001, value: 'new value' } }

Output Description: JSON object containing the test case ID, version ID, summary, update/creation metadata. When withVersion=true (version creation), response includes new version number and version ID. When withVersion=false/omitted (existing version update), response includes updated fields confirmation.

Use Cases: 1. Update test case summary (name) 2. Change priority, owner, or state of a test case 3. Edit, add, or remove test steps 4. Update only metadata (no steps) 5. Create a new version of a test case (withVersion=true) 6. Update a specific version of a test case (without withVersion flag) 7. Bulk update using entityKey auto-resolution 8. Modify test case description or estimated time 9. Change test case type or component 10. Update testing type or custom fields 11. Update, add and remove test case steps 12. Version control for test case evolution tracking

Examples:

1. Update test case summary (existing version update)

{
  "tcID": 4519260,
  "tcVersionID": 5448492,
  "name": "MAC Test11"
}

Expected Output: Test case summary updated. tcID and tcVersionID auto-resolved from entityKey. Only 'name' field changed. Version remains the same.

2. Create NEW VERSION with updated summary and description

{
  "tcID": 4572654,
  "tcVersionID": 5514384,
  "tcVersion": 1,
  "name": "Add two numbers 2 v2",
  "description": "Test Description version 2",
  "withVersion": true,
  "versionComment": "version 2 comment add",
  "notruncurrent": true,
  "notrunall": true
}

Expected Output: New version created (version 2). Test case now has incremental version with updated summary and description. Original version 1 remains unchanged.

3. Create NEW VERSION with all metadata fields (release, cycle, priority, owner, etc.)

{
  "tcID": 4572654,
  "tcVersionID": 5514384,
  "tcVersion": 1,
  "name": "Facebook Login Validation Failed update from MCP V2",
  "description": "Existing description V2",
  "priority": 2355751,
  "testcaseOwner": 6963,
  "testCaseState": 2355753,
  "testCaseType": 2355762,
  "estimatedTime": 7200,
  "withVersion": true,
  "versionComment": "Created version 2 with updated metadata",
  "notruncurrent": true,
  "notrunall": true,
  "folderPath": 602290,
  "scope": "project"
}

Expected Output: New test case version 2 created with updated summary, description, priority (High), owner (umang.savaliya), state, type, and estimated time (2 hours). Version comment added for tracking.

4. Update EXISTING VERSION 2 (not creating new version)

{
  "tcID": 4572654,
  "tcVersionID": 5514385,
  "name": "Updated version 2 name",
  "priority": 2355752
}

Expected Output: Version 2 updated with new name and priority. No new version created because withVersion flag is not set. This is a normal update of existing version.

5. Update priority to High and owner to john.doe (existing version)

{
  "tcID": 4519260,
  "tcVersionID": 5448492,
  "priority": 505015,
  "testcaseOwner": 6963
}

Expected Output: Priority and owner updated. Field IDs auto-resolved from project info. tcID/tcVersionID resolved from entityKey. Existing version modified.

6. Update steps (edit, add, remove) - existing version

{
  "tcID": 4519260,
  "tcVersionID": 5448492,
  "steps": [
    {
      "orderId": 1,
      "description": "Step 22",
      "inputData": "Input 22",
      "expectedOutcome": "Outcome 22",
      "tcStepID": 3014032
    },
    {
      "orderId": 2,
      "description": "Step3",
      "inputData": "Input 3",
      "expectedOutcome": "Outcome 3"
    }
  ],
  "removeSteps": [
    {
      "tcStepID": 3014031,
      "description": "Step 1",
      "orderId": 1
    }
  ],
  "isStepUpdated": true
}

Expected Output: Steps updated: Step 22 edited (tcStepID preserved), Step3 added (no tcStepID), Step 1 removed. tcID/tcVersionID auto-resolved. Existing version modified.

7. Create NEW VERSION with updated steps

{
  "tcID": 4572654,
  "tcVersionID": 5514384,
  "tcVersion": 1,
  "name": "Add two numbers 2 v2",
  "steps": [
    {
      "orderId": 1,
      "description": "I and u have a calculator",
      "inputData": "",
      "expectedOutcome": "",
      "tcStepID": 38001791
    },
    {
      "orderId": 2,
      "description": "I add 41 and 31",
      "inputData": "",
      "expectedOutcome": "",
      "tcStepID": 38001793
    },
    {
      "orderId": 3,
      "description": "the result should be 72",
      "inputData": "",
      "expectedOutcome": "",
      "tcStepID": 38001792
    }
  ],
  "withVersion": true,
  "versionComment": "version 2 with preserved steps",
  "notruncurrent": true,
  "notrunall": true,
  "isStepUpdated": true
}

Expected Output: New version 2 created with all steps from version 1 preserved. Steps carry forward with their tcStepID values. Version comment added for tracking.

8. Update only metadata (no steps) - existing version

{
  "tcID": 4519260,
  "tcVersionID": 5448492,
  "updateOnlyMetadata": true,
  "name": "New Name"
}

Expected Output: Metadata updated only. Steps unchanged. tcID/tcVersionID auto-resolved. Existing version modified.

9. Create NEW VERSION from existing version 2 with updated steps (working payload for linked test cases)

{
  "tcID": 4594145,
  "tcVersionID": 5536706,
  "tcVersion": 2,
  "name": "Mock Test Case - E-commerce Checkout Flow - v3",
  "steps": [
    {
      "orderId": 1,
      "description": "Open browser and navigate to e-commerce website",
      "expectedOutcome": "Homepage loads successfully with product catalog",
      "inputData": "URL: https://example-shop.com",
      "tcStepID": 38129471
    },
    {
      "orderId": 2,
      "description": "Search for product",
      "expectedOutcome": "Search results display relevant products",
      "inputData": "Search term: 'wireless headphones'",
      "tcStepID": 38129475
    },
    {
      "orderId": 3,
      "description": "Select product and add to cart",
      "expectedOutcome": "Product added to cart, cart counter increments",
      "inputData": "Click 'Add to Cart' button",
      "tcStepID": 38129472
    },
    {
      "orderId": 4,
      "description": "Proceed to checkout",
      "expectedOutcome": "Checkout page displays with cart summary",
      "inputData": "Click cart icon and 'Proceed to Checkout'",
      "tcStepID": 38129473
    },
    {
      "orderId": 5,
      "description": "Complete payment",
      "expectedOutcome": "Order confirmation page displayed",
      "inputData": "Fill payment details and submit",
      "tcStepID": 38129474
    },
    {
      "orderId": 6,
      "description": "Verify order confirmation email received",
      "expectedOutcome": "Email with order details received in inbox",
      "inputData": "Check email account for confirmation"
    },
    {
      "orderId": 7,
      "description": "Check order status in account dashboard",
      "expectedOutcome": "Order status shows as 'Processing' with tracking information",
      "inputData": "Navigate to My Orders section"
    }
  ],
  "withVersion": true,
  "versionComment": "Created version 3: Added 2 new verification steps (email and order status check)",
  "notrunall": false,
  "notruncurrent": false,
  "scope": "project"
}

Expected Output: New version 3 created successfully from version 2. Test case now has 7 steps (5 preserved + 2 new). Key: tcVersion=2 was used because version 2 already existed in system. notrunall and notruncurrent both false (not true). Result shows tcVersion: 3 in response with new tcVersionID.

Hints: 1. === DEFAULT VALUES — APPLY FOR ANY UNSET FIELD === 2. Call 'Fetch UDF Layout' with entityType='TC', pageName='DETAIL' before updating. 3. defaultValues (from Fetch UDF Layout): { fieldName: defaultValueId } — sweep ALL entries. 4. For EACH key in defaultValues: if user did not explicitly provide that field → include it in payload with the default value. 5. This applies to non-mandatory fields too (e.g. priority, estimatedTime). Omitting them = data loss. 6. === END DEFAULT VALUES === 7. 8. === DATE FORMAT CHECK (MANDATORY — EVERY UPDATE REQUEST) === 9. ALWAYS call 'Fetch QMetry Project Info' before every update request — not only when the user explicitly mentions a date. 10. Any UDF field could be a DATETIMEPICKER. Wrong format causes QMetry to silently discard the field value (API returns success but value is NOT stored — no error). 11. STEP 1: From project info, read dateTimeFormatID (e.g. 3). 12. STEP 2: Find entry in dateTimeFormatNew where id === dateTimeFormatID → read its unique_value (e.g. 'yyyy-MM-dd'). 13. STEP 3: unique_value pattern: yyyy=4-digit year, MM=2-digit month (01-12), dd=2-digit day, MMM=3-letter month (Jan/Feb/...). 14. Example: id=1 → MM-dd-yyyy → '10-25-2000' | id=2 → dd-MM-yyyy → '25-10-2000' | id=3 → yyyy-MM-dd → '2000-10-25' | id=4 → dd-MMM-yyyy → '25-Oct-2000' 15. STEP 4: For EVERY DATETIMEPICKER field in the payload: parse any user-provided date and re-format it using the active unique_value pattern before sending. 16. NEVER assume a date format — always derive it from dateTimeFormatID. Wrong format = silent data loss. 17. === END DATE FORMAT CHECK === 18. 19. CRITICAL - VERSION CREATION vs UPDATE DISTINCTION: 20. This tool supports TWO MODES using the SAME API endpoint: 21. 22. MODE 1: CREATE NEW VERSION (withVersion=true) 23. - Purpose: Create an incremental version of the test case (e.g., v1 → v2, v2 → v3) 24. - When to use: User explicitly asks to 'create new version', 'create version 2', 'increment version' 25. - Required fields: tcID, tcVersionID (of source version), tcVersion (current version number), withVersion=true 26. - Optional but recommended: versionComment (track what changed), notruncurrent, notrunall 27. - Behavior: Creates a NEW test case version with incremented version number. Source version remains unchanged. 28. - Example: If current version is 1, setting withVersion=true creates version 2 29. - Use cases: Updating test case for new requirements, creating variants for different scenarios, version control 30. 31. MODE 2: UPDATE EXISTING VERSION (withVersion=false or omitted) 32. - Purpose: Modify fields of an EXISTING version without creating a new version 33. - When to use: User asks to 'update test case', 'modify version X', 'change summary' (without mentioning new version) 34. - Required fields: tcID, tcVersionID (of version to update) 35. - Do NOT include: withVersion flag, versionComment, tcVersion 36. - Behavior: Updates the specified version in-place. No new version is created. 37. - Example: Updating version 2's summary - only version 2 is modified, no version 3 is created 38. - Use cases: Fixing typos, updating metadata, modifying steps in existing version 39. 40. CRITICAL FIELD UNDERSTANDING: 41. - tcVersionID: The VERSION ID (numeric identifier) of the version you're working with 42. - tcVersion: The VERSION NUMBER (1, 2, 3, etc.) - only needed when withVersion=true 43. - tcID: The TEST CASE ID (remains same across all versions) 44. - Example: Test case VKMCP-TC-10 (tcID: 4572654) has version 1 (tcVersionID: 5514384, tcVersion: 1) 45. - When creating version 2 from version 1: Send tcVersionID=5514384 (source), tcVersion=1 (current), withVersion=true 46. 47. HOW TO DETERMINE WHICH MODE: 48. - User says 'create new version' → MODE 1 (withVersion=true) 49. - User says 'create version 2' → MODE 1 (withVersion=true) 50. - User says 'update test case with new version' → MODE 1 (withVersion=true) 51. - User says 'update test case VKMCP-TC-10 summary' → MODE 2 (no withVersion, update existing version) 52. - User says 'update version 2 summary' → MODE 2 (no withVersion, update existing version 2) 53. - User says 'change priority of version 1' → MODE 2 (no withVersion, update version 1) 54. - If ambiguous, ask user: 'Do you want to create a new version or update the existing version?' 55. 56. VERSION CREATION WORKFLOW (withVersion=true): 57. Step 1: Fetch test case details to get current tcID, tcVersionID, and tcVersion 58. Step 2: Optionally fetch current steps if they need to be preserved/modified 59. Step 3: Prepare payload with: 60. - tcID (test case ID) 61. - tcVersionID (source version ID to create from) 62. - tcVersion (current version number) 63. - withVersion: true (CRITICAL flag) 64. - versionComment (recommended: describe what changed) 65. - Updated fields (name, description, priority, steps, etc.) 66. - notruncurrent: true (recommended) 67. - notrunall: true (recommended) 68. Step 4: Call update API - a new version will be created with incremented version number 69. Step 5: New version inherits all fields from source version, with your specified updates applied 70. 71. EXISTING VERSION UPDATE WORKFLOW (no withVersion): 72. Step 1: Fetch test case details to get tcID and tcVersionID of the version to update 73. Step 2: Prepare payload with: 74. - tcID (test case ID) 75. - tcVersionID (version ID to update) 76. - DO NOT include withVersion, versionComment, or tcVersion 77. - Only include fields you want to change 78. Step 3: Call update API - specified version is updated in-place 79. Step 4: No new version is created, only specified fields are modified 80. 81. FIELD MAPPING FOR VERSION CREATION: 82. When creating a new version, include ALL fields you want the new version to have: 83. - name: Test case summary (required if different from source) 84. - description: Test case description (required if different from source) 85. - priority: Priority ID (get from project info customListObjs.priority[index].id) 86. - testcaseOwner: Owner ID (get from project info customListObjs.owner[index].id) 87. - testCaseState: State ID (get from project info customListObjs.testCaseState[index].id) 88. - testCaseType: Type ID (get from project info customListObjs.testCaseType[index].id) 89. - testingType: Testing type ID (get from project info customListObjs.testingType[index].id) 90. - component: Array of component IDs (get from project info customListObjs.component[index].id) 91. - estimatedTime: Time in seconds (e.g., 7200 for 2 hours) 92. - steps: Array of step objects (include tcStepID from source version to preserve steps) 93. - folderPath: Folder path or folder ID 94. - scope: Usually 'project' 95. 96. STEPS HANDLING IN VERSION CREATION: 97. When creating a new version WITH steps: 98. - To PRESERVE existing steps: Include them with their original tcStepID values 99. - To ADD new steps: Include them WITHOUT tcStepID 100. - To MODIFY steps: Include them with tcStepID and updated description/data 101. - To REMOVE steps: Include them in removeSteps array 102. - Set isStepUpdated: true if any steps are modified, added, or removed 103. - If no steps are included, new version may inherit steps from source (verify with QMetry docs) 104. 105. If user provides entityKey (e.g., MAC-TC-1684), first call FETCH_TEST_CASES with a filter on entityKeyId to resolve the tcID and tcVersionID. 106. To get valid values for priority, owner, component, etc., call the project info tool and use the returned customListObjs IDs. 107. If the user provides a priority name (e.g. 'Blocker'), fetch project info, find the matching priority in customListObjs.priority[index].name, and use its ID in the payload. If the name is not found, skip the priority field (it is not required) and show a user-friendly message: 'Test case updated without priority, as given priority is not available in the current project.' 108. If the user provides a component name, fetch project info, find the matching component in customListObjs.component[index].name, and use its ID in the payload. If the name is not found, skip the component field (it is not required) and show a user-friendly message: 'Test case updated without component, as given component is not available in the current project.' 109. If the user provides an owner name, fetch project info, find the matching owner in customListObjs.owner[index].name, and use its ID in the payload as testcaseOwner. If the name is not found, skip the testcaseOwner field (it is not required) and show a user-friendly message: 'Test case updated without owner, as given owner is not available in the current project.' 110. If the user provides a test case state name, fetch project info, find the matching state in customListObjs.testCaseState[index].name, and use its ID in the payload as testCaseState. If the name is not found, skip the testCaseState field (it is not required) and show a user-friendly message: 'Test case updated without test case state, as given state is not available in the current project.' 111. If the user provides a test case type name, fetch project info, find the matching type in customListObjs.testCaseType[index].name, and use its ID in the payload as testCaseType. If the name is not found, skip the testCaseType field (it is not required) and show a user-friendly message: 'Test case updated without test case type, as given type is not available in the current project.' 112. If the user provides a testing type name, fetch project info, find the matching type in customListObjs.testingType[index].name, and use its ID in the payload as testingType. If the name is not found, skip the testingType field (it is not required) and show a user-friendly message: 'Test case updated without testing type, as given testing type is not available in the current project.' 113. Example: If user says 'Update test case with title "High priority test case" and set priority to "Blocker"', first call project info, map 'Blocker' to its ID, and use that ID for the priority field in the update payload. If user says 'set priority to "Urgent"' and 'Urgent' is not found, skip the priority field and show: 'Test case updated without priority, as given priority is not available in the current project.' 114. CRITICAL: To update test case steps without Duplication, use the following rules: 115. - ANTI-DUPLICATION RULE: The tcStepID field is THE KEY to prevent duplication: 116. * WITH tcStepID = UPDATE existing step (QMetry modifies the existing step in place) 117. * WITHOUT tcStepID = CREATE new step (QMetry adds a brand new step) 118. - For steps to be UPDATED: ALWAYS fetch existing steps first using FETCH_TEST_CASE_STEPS, then include the tcStepID in the step object. 119. - For steps to be ADDED: omit tcStepID completely in the step object. 120. - For steps to be REMOVED: add a full removeSteps object for each step to be deleted, matching the removeTestCaseStep interface. 121. - CRITICAL WARNING - DO NOT ADD UNSOLICITED STEPS: 122. * ONLY add, edit, or remove steps that the user EXPLICITLY requested 123. * DO NOT invent, create, or add extra steps based on assumptions or best practices 124. * DO NOT add 'helpful' steps that the user did not ask for 125. * When user says 'remove step 1', the result should have (N-1) steps, not N steps with extras 126. * When user says 'add 1 step', ONLY add that 1 step, nothing more 127. * When user says 'update step 2', ONLY update step 2, do not add or modify other steps 128. * If unsure what user wants, ASK first rather than adding steps autonomously 129. - WORKFLOW TO AVOID DUPLICATION: 130. 1. Call FETCH_TEST_CASE_STEPS to get all existing steps with their tcStepID values 131. 2. For steps you want to KEEP/UPDATE: Include them in steps[] WITH their original tcStepID 132. 3. For steps you want to ADD: Include them in steps[] WITHOUT tcStepID (ONLY if user requested) 133. 4. For steps you want to REMOVE: Include them in removeSteps[] with full details 134. 5. Always set isStepUpdated: true if steps are added, updated, or removed 135. 6. VERIFY your steps array matches user's explicit request (count and content) 136. - Example: If user says 'Edit step 1 to say ...', FIRST fetch steps to get tcStepID for step 1, THEN include it in the steps array with updated fields and the ORIGINAL tcStepID. 137. - Example: If user says 'Add a new step after step 2', add EXACTLY ONE new object to steps array with no tcStepID (not multiple steps). 138. - Example: If user says 'Remove step 3', add the full step object to removeSteps array, including tcStepID and all required fields. Do NOT add replacement steps. 139. - Example: If test case has 3 steps and user says 'remove step 1', result should have 2 steps (step 2 and step 3 with updated orderIds), NOT 3 steps with extras. 140. - Example: If user says 'add one mock step', add EXACTLY ONE step (not 2 or 3 steps even if they seem related). 141. - COMPLETE PAYLOAD EXAMPLE: { tcID: 123, tcVersionID: 456, steps: [{tcStepID: 1001, orderId: 1, description: 'Updated'}, {orderId: 2, description: 'New'}], removeSteps: [{tcStepID: 1002, orderId: 3, ...}], isStepUpdated: true } 142. - If only metadata is updated (no steps), set updateOnlyMetadata: true and do not include steps/removeSteps. 143. - Always preserve orderId sequence for proper step ordering. 144. - If user prompt is ambiguous, ask for clarification or show a user-friendly error. 145. - WARNING: Omitting tcStepID for existing steps will cause DUPLICATION - the API will create duplicates instead of updating! 146. - FINAL VERIFICATION BEFORE SENDING REQUEST: 147. * Count steps in your payload vs what user requested 148. * If user said 'add 1 step', steps array should have (existing_count + 1) items total 149. * If user said 'remove 1 step', steps array should have (existing_count - 1) items total, removeSteps should have 1 item 150. * If user said 'update step X', steps array should have same count as before, with step X's tcStepID preserved 151. * NEVER include steps the user did not explicitly mention or request 152. Steps are optional but recommended for manual test cases. 153. If the user provides a prompt like 'update test case with steps as step 1 - Go to login page, step 2 - give credential, step 3 - go to test case page, step 4 - create test case', LLM should parse each step and convert it into the steps payload array, mapping each step to an object with orderId, description, and optionally inputData and expectedOutcome. 154. Example mapping: 'step 1 - Go to login page' → { orderId: 1, description: 'Go to login page' }. 155. LLM should increment orderId for each step, use the step text as description, and optionally infer inputData/expectedOutcome if provided in the prompt. 156. Demo steps payload: steps: [ { orderId: 1, description: 'First Step', inputData: 'First Data', expectedOutcome: 'First Outcome', UDF: { customField1: 'Custom Field Data A', customField2: 'Custom Field Data B' } }, ... ] 157. UDF fields in steps must match your QMetry custom field configuration. 158. All IDs (priority, owner, etc.) must be valid for your QMetry instance. 159. If a custom field is mandatory, include it in the UDF object. 160. 161. ADDITIONAL VERSION CREATION GUIDANCE: 162. - versionComment field: STRONGLY RECOMMENDED when withVersion=true. Helps track why version was created. 163. Example comments: 'Updated for Sprint 5 requirements', 'Fixed test steps based on code review', 'Version 2 for production environment' 164. - notruncurrent and notrunall flags: Control execution behavior when creating versions. Set both to true as best practice. 165. - folderPath: Can be string path or numeric folder ID. Usually inherited from source version if not specified. 166. - attachments: Use ADD/REMOVE arrays to manage attachments when creating new version or updating existing version. 167. - estimatedTime vs executionMinutes: Use estimatedTime (in seconds) for version creation. executionMinutes (in minutes) is legacy field. 168. 169. REAL-WORLD VERSION CREATION EXAMPLES: 170. Example 1: User says 'create a new version of test case VKMCP-TC-10 with summary = "Facebook Login Validation Failed update from MCP V2", description = used existing description by at last add V2 text, release = default, cycle = default' 171. → Workflow: 172. 1. Fetch VKMCP-TC-10 details to get tcID, tcVersionID, tcVersion, current description 173. 2. Fetch project info to get default release ID and cycle ID 174. 3. Append ' V2' to current description 175. 4. Send payload with: tcID, tcVersionID (source), tcVersion (current), withVersion=true, name='...V2', description='...V2', versionComment='Created version 2', release/cycle IDs 176. → Result: New incremental version created (e.g., version 1 → version 2) with updated summary, modified description, associated with default release/cycle 177. 178. Example 2: User says 'update version 2 summary, release, cycle, priority' 179. → Workflow: 180. 1. Fetch test case details to get version 2's tcVersionID 181. 2. Fetch project info to get priority, release, cycle IDs 182. 3. Send payload with: tcID, tcVersionID (of version 2), WITHOUT withVersion flag, with updated summary, release, cycle, priority 183. → Result: Version 2 updated in-place. No new version created. Only specified fields modified. 184. 185. COMMON PITFALLS TO AVOID: 186. - Pitfall 1: Setting withVersion=true when user wants to update existing version → Creates unwanted new version 187. - Pitfall 2: Omitting versionComment when creating new version → Lost tracking of why version was created 188. - Pitfall 3: Not fetching current tcVersionID before update → Updating wrong version or causing error 189. - Pitfall 4: Using tcVersion for normal updates → tcVersion only needed when withVersion=true 190. - Pitfall 5: Not including tcStepID for steps when creating version → Steps may duplicate instead of preserving 191. - Pitfall 6: Confusing tcVersionID (version identifier) with tcVersion (version number) → Wrong API payload 192. 193. CRITICAL ERROR HANDLING: TC.VERSION_NOT_SYNCED FOR LINKED TEST CASES 194. 195. PROBLEM: Test cases linked to test suites or with existing executions cannot be updated directly 196. TRIGGERS: 197. ✓ Test case is linked to one or more test suites 198. ✓ Test case has execution history (test runs exist) 199. ✓ Test case is part of a release/cycle with test runs 200. ✓ Any step modification when test case has associations 201. 202. ERROR CODE: TC.VERSION_NOT_SYNCED 203. ERROR MESSAGE: 'This Test Case has been associated. Create a new version to save modifications.' 204. 205. AUTOMATIC RETRY STRATEGY (IMPLEMENT THIS PATTERN): 206. When you receive TC.VERSION_NOT_SYNCED error, AUTOMATICALLY retry with version creation: 207. DO NOT ask user for confirmation - this is expected behavior for associated test cases 208. 209. 1. FIRST ATTEMPT (Normal Update): 210. - Try updating with isStepUpdated=true (for step changes) or without withVersion flag 211. - If error code is TC.VERSION_NOT_SYNCED, proceed to step 2 212. - If error is different, report the error to user 213. 214. 2. AUTOMATIC RETRY (Version Creation): 215. - Use the SAME tcID, tcVersionID, and steps array from first attempt 216. - Add these flags to payload: 217. * withVersion: true (CRITICAL - enables version creation) 218. * tcVersion: (get from test case details or executions) 219. * notrunall: false (use false, not true) 220. * notruncurrent: false (use false, not true) 221. * scope: 'project' (always required) 222. * versionComment: 'Auto-created version due to test suite association' (or custom message) 223. - Set isStepUpdated: true whenever you modify steps (including when withVersion=true) 224. - IMPORTANT: Include ALL existing steps with tcStepID + new steps without tcStepID 225. 226. 3. VERIFICATION: 227. - Check response for new tcVersionID (will be different from source) 228. - Verify tcVersion incremented (e.g., 1→2, 2→3) 229. - Confirm success message: 'Test Case updated successfully' 230. 231. UI BEHAVIOR COMPARISON: 232. QMetry UI shows a popup: 'Save as new version?' with optional comment field 233. API equivalent: Automatic retry with withVersion=true after detecting TC.VERSION_NOT_SYNCED 234. 235. REAL-WORLD EXAMPLE FROM UI PAYLOADS: 236. 237. First Attempt (FAILS with TC.VERSION_NOT_SYNCED): 238. pseudo 239. { 240. "tcID": 4594140, 241. "tcVersionID": 5536696, 242. "withVersion": false, 243. "notrunall": false, 244. "steps": [ 245. // ... 5 existing steps with tcStepID ... 246. // ... 1 new step without tcStepID (orderId: 6) ... 247. ], 248. "removeSteps": [], 249. "isStepUpdated": true 250. } 251. 252. Response: 400 - TC.VERSION_NOT_SYNCED error 253. 254. Second Attempt (SUCCEEDS - Creates Version 2): 255. pseudo 256. { 257. "withVersion": true, // NEW: Version creation flag 258. "notrunall": false, 259. "notruncurrent": false, 260. "steps": [ 261. // SAME steps array as first attempt 262. // ... 5 existing steps with tcStepID ... 263. // ... 1 new step without tcStepID ... 264. ], 265. "removeSteps": [], 266. "scope": "project", 267. "tcID": 4594140, // SAME tcID 268. "tcVersion": 1, // NEW: Current version number 269. "tcVersionID": 5536696, // SAME tcVersionID (source version) 270. "versionComment": "test", // NEW: Version comment (optional) 271. // NOTE: isStepUpdated field is NOT included when withVersion=true 272. } 273. 274. Response: 200 - Success, new tcVersionID created (e.g., 5536697), tcVersion=2 275. 276. IMPLEMENTATION PSEUDO-CODE: 277. typescript 278. try { 279. // First attempt: Normal update 280. const response = await updateTestCase({ 281. tcID, tcVersionID, steps, isStepUpdated: true 282. }); 283. } catch (error) { 284. if (error.code === 'TC.VERSION_NOT_SYNCED') { 285. // Automatic retry with version creation 286. const testCaseDetails = await fetchTestCaseDetails(tcID); 287. // CRITICAL: Use the LATEST version number from system 288. const latestVersion = testCaseDetails.tcVersion; // e.g., 2 if v2 exists 289. const response = await updateTestCase({ 290. tcID, 291. tcVersionID, // Same source version 292. tcVersion: latestVersion, // Use latest version number (not always 1!) 293. steps, // Same steps array 294. // DO NOT include isStepUpdated when withVersion=true 295. withVersion: true, // Enable version creation 296. notrunall: false, // Use false (verified working value) 297. notruncurrent: false, // Use false (verified working value) 298. scope: 'project', // Always required 299. versionComment: 'Auto-created version due to test suite association' 300. }); 301. } else { 302. throw error; // Different error, report to user 303. } 304. } 305. 306. 307. KEY INSIGHTS: 308. - DO NOT ask user for confirmation - auto-retry is expected behavior 309. - Use SAME tcVersionID in both attempts (source version for creation) 310. - Second attempt creates NEW version (tcVersionID changes in response) 311. - Steps array is IDENTICAL in both attempts 312. - tcVersion parameter is ONLY in second attempt (withVersion=true) 313. - This matches QMetry UI behavior where popup auto-triggers version creation 314. 315. CRITICAL: INCREMENTAL tcVersion SELECTION RULE 316. 317. PROBLEM: When multiple versions exist, which tcVersion should you use? 318. SOLUTION: Use the VERSION NUMBER of the version you are creating FROM (the latest existing version) 319. 320. RULE: When creating a new version, tcVersion must equal the CURRENT LATEST VERSION in the system 321. 322. EXAMPLES: 323. - If only version 1 exists: Use tcVersion: 1 (creates version 2 from v1) 324. - If version 1 and 2 exist: Use tcVersion: 2 (creates version 3 from v2) 325. - If version 1, 2, and 3 exist: Use tcVersion: 3 (creates version 4 from v3) 326. 327. WORKFLOW TO DETERMINE CORRECT tcVersion: 328. 1. Call FETCH_TEST_CASE_DETAILS or FETCH_TEST_CASE_EXECUTIONS 329. 2. Check the highest tcVersion number in the system 330. 3. Use that number as your tcVersion parameter in the update payload 331. 4. This ensures you're creating from the latest version, not an old one 332. 333. REAL-WORLD SCENARIO: 334. Scenario: Test case VKMCP-TC-43 has version 2 already created in UI 335. Wrong Approach (will fail): tcVersion: 1, withVersion: true → TC.VERSION_NOT_SYNCED error 336. Correct Approach (will succeed): tcVersion: 2, withVersion: true → Creates version 3 successfully 337. 338. VERIFIED WORKING PAYLOAD (from user's Postman testing): 339. json 340. { 341. "notrunall": false, 342. "notruncurrent": false, 343. "scope": "project", 344. "tcID": 4594145, 345. "tcVersion": 2, // KEY: Use version 2 because v2 already exists 346. "tcVersionID": 5536706, // Source version ID (stays same) 347. "versionComment": "Added new steps", // Describes what changed 348. "withVersion": true, // Enable version creation 349. "steps": [ 350. // 5 existing steps with tcStepID (preserved from source) 351. // 2 new steps without tcStepID (to be added) 352. ] 353. } 354. 355. Result: New version 3 created successfully with 7 total steps 356. 357. DEFAULT VALUES FOR TC.VERSION_NOT_SYNCED RETRIES (THIS PATTERN): 358. - notrunall: false - For this retry pattern, override any usual true default 359. - notruncurrent: false - For this retry pattern, override any usual true default 360. - scope: "project" - Always use this 361. - withVersion: true - Required when creating a new version (both initial and retries) 362. 363. WHEN TO APPLY THIS PATTERN: 364. ✓ Adding steps to test case linked to test suite 365. ✓ Editing steps in test case with existing executions 366. ✓ Removing steps from associated test case 367. ✓ Any modification to steps when TC.VERSION_NOT_SYNCED occurs 368. ✓ When creating new versions from existing versions (always check latest version number) 369. 370. WHEN NOT TO APPLY: 371. ✗ Test case is NOT linked to test suite (normal update works) 372. ✗ Only updating metadata (name, priority, etc.) without steps 373. ✗ Different error codes (handle appropriately) 374. 375. BENEFITS OF THIS APPROACH: 376. 1. Seamless UX - LLM handles version creation automatically 377. 2. Matches UI behavior - no manual intervention needed 378. 3. Preserves test history - creates proper version trail 379. 4. Maintains test suite linkage - version creation preserves associations 380. 5. Handles incremental versions correctly - uses latest version as source 381. 382. 🎯 GRACEFUL HANDLING SUMMARY: 383. 384. When adding/editing/removing steps from test cases: 385. 1. Always TRY normal update first (without withVersion flag) 386. 2. If TC.VERSION_NOT_SYNCED error received: 387. - Fetch latest version number from test case details/executions 388. - Automatically retry with withVersion=true + correct tcVersion 389. - Use notrunall=false, notruncurrent=false, scope='project' 390. - Include version comment describing the changes 391. 3. Report success with new version details to user 392. 4. NEVER ask for confirmation - handle it transparently 393. 394. This ensures test cases with executions or suite associations are handled gracefully 395. without user intervention, matching the QMetry UI experience exactly. 396. 397. executionMinutes time is in minutes (legacy field). 398. estimatedTime is in seconds (preferred for version creation). 399. Description and testingType are optional but recommended for clarity. 400. 401. UDF (User Defined Fields) WORKFLOW FOR UPDATE: 402. 1. Call 'Fetch UDF Layout' with entityType='TC', pageName='DETAIL' to get field names, fieldIDs (projectUserFieldID), and list option IDs. 403. IF listOptions[field.listName] is empty after Fetch UDF Layout, the tool already tried a metadata fallback. If STILL empty, ask the user to provide the option ID from the QMetry UI — do NOT guess numeric IDs. 404. 2. For LOOKUPLIST fields: pick one ID from listOptions[field.listName][].id. 405. 3. For MULTILOOKUPLIST fields: pick an array of IDs; also pass the alias flat key (e.g., fieldNameAlias: 'Option Label'). 406. 4. For CASCADINGLIST fields: pick parent ID + fetch child with 'Fetch Cascade Child Values'. Pass { parent: parentId, child: childId }. 407. 5. Pass BOTH 'udfFields' (flat root values) AND 'UDF' wrapper (with fieldID) — both required for update. 408. Example: udfFields: { custom_text: 'new value' }, UDF: { custom_text: { fieldID: 1001, value: 'new value' } } 409. 6. Mandatory UDF fields (isMandatory=true) MUST be included. 410. STEP UDFs for update: Use same step UDF field names from 'Fetch UDF Layout' stepFields. Pass in each step's 'UDF' object. 411. For MULTILOOKUPLIST step UDFs in update: use { ADD: [id1, id2], REMOVE: [id3] } format.

Fetch QMetry test cases - automatically handles viewId resolution based on project

Toolset: Test Cases

Parameters:

• projectKey (string): Project key - unique identifier for the project (default: "default")

• viewId (number): ViewId for test cases - SYSTEM AUTOMATICALLY RESOLVES THIS. Leave empty unless you have a specific viewId. System will fetch project info using the projectKey and extract latestViews.TC.viewId automatically.

• folderPath (string): Folder path for test cases - SYSTEM AUTOMATICALLY SETS TO ROOT. Leave empty unless you want specific folder. System will automatically use empty string "" (root directory). Only specify if user wants specific folder like "Automation/Regression". (default: "")

• folderID (number): Folder ID - unique numeric identifier for the specific folder. Use this to target a specific folder within the project hierarchy. Applies to any entity type (test cases, requirements, test suites, etc.).

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

• scope (string): Scope of the operation - defines the context for data retrieval. Common values: 'project' (default), 'folder', 'release', 'cycle'. Applies to any entity type being fetched or operated upon. (default: "project")

• showRootOnly (boolean): Whether to show only root folders.

• getSubEntities (boolean): Whether to include sub-entities.

• hideEmptyFolders (boolean): Whether to hide empty folders.

• folderSortColumn (string): Folder sort column (default 'name')

• restoreDefaultColumns (boolean): Whether to restore default columns (default 'false')

• folderSortOrder (string): Folder sort order (ASC or DESC)

• filter (string): Filter criteria as JSON string (default '[]') (default: "[]")

• udfFilter (string): User-defined field filter as JSON string (default '[]') (default: "[]")

Output Description: JSON object with 'data' array containing test cases and pagination info

Use Cases: 1. List all test cases in a project (without filters) 2. Browse test cases in specific folders for bulk operations 3. Get paginated test case results for reporting 4. Export multiple test cases at once

Examples:

1. Get all test cases from default project - system will auto-fetch viewId

{}

Expected Output: List of test cases from default project with auto-resolved viewId

2. Get all test cases from UT project - system will auto-fetch UT project's viewId

{
  "projectKey": "UT"
}

Expected Output: List of test cases from UT project using UT's specific TC viewId

3. Get test cases by release/cycle filter

{
  "projectKey": "MAC",
  "filter": "[{\"value\":[55178],\"type\":\"list\",\"field\":\"release\"},{\"value\":[111577],\"type\":\"list\",\"field\":\"cycle\"}]"
}

Expected Output: Test cases associated with Release 8.12 (ID: 55178) and Cycle 8.12.1 (ID: 111577)

4. Get test cases by release only

{
  "projectKey": "MAC",
  "filter": "[{\"value\":[55178],\"type\":\"list\",\"field\":\"release\"}]"
}

Expected Output: All test cases associated with Release 8.12 (ID: 55178)

5. Get test cases by cycle only

{
  "projectKey": "MAC",
  "filter": "[{\"value\":[111577],\"type\":\"list\",\"field\":\"cycle\"}]"
}

Expected Output: All test cases associated with Cycle 8.12.1 (ID: 111577)

6. Search for specific test case by entity key

{
  "projectKey": "MAC",
  "filter": "[{\"type\":\"string\",\"value\":\"MAC-TC-1684\",\"field\":\"entityKeyId\"}]"
}

Expected Output: Test cases matching the entity key criteria

7. Search for multiple test cases by comma-separated entity keys

{
  "projectKey": "MAC",
  "filter": "[{\"type\":\"string\",\"value\":\"MAC-TC-1684,MAC-TC-1685,MAC-TC-1686\",\"field\":\"entityKeyId\"}]"
}

Expected Output: Test cases matching any of the specified entity keys

Hints: 1. CRITICAL - FILTER PERSISTENCE WARNING: 2. DO NOT use this API with filters to fetch a single test case by ID, entityKey, or name! 3. Filters applied to this API persist in the production UI and cause only filtered records to be visible to users. 4. This creates a major UX problem where users see incomplete data in their QMetry portal. 5. 6. CORRECT APPROACH FOR SINGLE TEST CASE: 7. When user asks to 'fetch test case VKMCP-TC-5' or 'get test case by ID 123' or 'find test case named X': 8. 1. Ask user for the numeric test case ID (tcID) if not provided 9. 2. Use 'Fetch Test Case Details' tool with the numeric tcID parameter 10. 3. NEVER use 'Fetch Test Cases' with entityKeyId filter for single test case lookup 11. 12. WHEN TO USE THIS TOOL: 13. Only use this tool when user explicitly asks for: 14. - 'List all test cases' 15. - 'Show me test cases in folder X' 16. - 'Get all test cases' (without specifying a single test case) 17. - 'Export test cases' (for bulk operations) 18. 19. CRITICAL WORKFLOW: Always use the SAME projectKey for both project info and test case fetching 20. Step 1: If user specifies projectKey (like 'UT', 'MAC'), use that EXACT projectKey for project info 21. Step 2: Get project info using that projectKey, extract latestViews.TC.viewId 22. Step 3: Use the SAME projectKey and the extracted TC viewId for fetching test cases 23. Step 4: If user doesn't specify projectKey, use 'default' for both project info and test case fetching 24. NEVER mix project keys - if user says 'MAC project', use projectKey='MAC' for everything 25. DEPRECATED: Do not use filter with entityKeyId for single test case - use 'Fetch Test Case Details' instead 26. RELEASE/CYCLE FILTERING: Use release and cycle IDs, not names, for filtering 27. For release filter: '[{"value":[releaseId],"type":"list","field":"release"}]' 28. For cycle filter: '[{"value":[cycleId],"type":"list","field":"cycle"}]' 29. For combined release+cycle: '[{"value":[releaseId],"type":"list","field":"release"},{"value":[cycleId],"type":"list","field":"cycle"}]' 30. Get release/cycle IDs from FETCH_RELEASES_AND_CYCLES tool before filtering 31. FILTER FIELDS: entityKeyId, priorityAlias, createdByAlias, updatedByAlias, testCaseStateAlias, testingTypeAlias, testCaseTypeAlias, componentAlias, owner, release, cycle 32. SORT FIELDS: entityKey, name, associatedVersion, priorityAlias, createdDate, createdByAlias, updatedDate, updatedByAlias, testCaseStateAlias, testingTypeAlias, executionMinutes 33. For multiple entity keys, use comma-separated values in filter 34. Use empty string '' as folderPath for root directory

Get detailed information for a specific QMetry test case by numeric ID - USE THIS for single test case lookup

Toolset: Test Cases

Parameters:

• projectKey (string): Project key - unique identifier for the project (default: "default")

• tcID (number) required: Test Case numeric ID. CRITICAL: the parameter name is 'tcID' — do NOT use 'testCaseId', 'testCaseID', 'tcId', or other variants. Accepts a string or number. This is the internal numeric identifier, not the entity key like 'MAC-TC-1684'. You can get this ID from test case search results or by using filters.

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

Output Description: JSON object with test case details including ID, key, summary, description, and metadata

Use Cases: 1. Get test case details by numeric ID (PREFERRED for single test case) 2. Fetch test case when user provides entityKey (e.g., 'VKMCP-TC-5') 3. Retrieve test case metadata for a specific test case 4. Get test case summary and properties for display or editing 5. Fetch test case details before accessing steps or version details 6. Lookup test case by name or ID without affecting UI filters

Examples:

1. Get test case details by numeric ID

{
  "tcID": 4468020
}

Expected Output: Detailed test case information including summary, description, status

Hints: 1. USE THIS TOOL when user asks to 'fetch test case VKMCP-TC-5' or 'get test case by ID' or 'find test case X' 2. This API requires a numeric tcID parameter 3. CRITICAL: If user provides entityKey (e.g., MAC-TC-1684), you have TWO options: 4. Option 1 (RECOMMENDED): Ask user for the numeric test case ID 5. Option 2: If you must resolve entityKey, use FETCH_TEST_CASES with filter ONLY ONCE, then immediately use this tool 6. After resolving entityKey → tcID, always use THIS tool (FETCH_TEST_CASE_DETAILS) for subsequent lookups 7. This tool provides metadata and properties; use FETCH_TEST_CASE_STEPS for step-level details 8. This tool does NOT persist filters in UI - safe for single test case lookups 9. ALWAYS prefer this tool over FETCH_TEST_CASES with filters for single test case operations

Get QMetry test case details for a specific version by numeric ID

Toolset: Test Cases

Parameters:

• projectKey (string): Project key - unique identifier for the project (default: "default")

• id (number) required: Test Case numeric ID (required for fetching steps or version details). Accepts a string or number. This is the internal numeric identifier, not the entity key like 'MAC-TC-1684'. You can get this ID from test case search results.

• version (number) required: Test Case version number. This is the internal numeric identifier for the version.

• scope (string): Scope of the operation - defines the context for data retrieval. Common values: 'project' (default), 'folder', 'release', 'cycle'. Applies to any entity type being fetched or operated upon. (default: "project")

Output Description: JSON object with version-specific test case details

Use Cases: 1. Get specific version details of a test case 2. Compare different versions of a test case 3. Retrieve version history information 4. Audit changes made across test case versions

Examples:

1. Get version 2 details for test case ID 123

{
  "id": 123,
  "version": 2
}

Expected Output: Version 2 details for test case 123

Hints: 1. Requires numeric ID, not entityKey 2. If user provides entityKey (e.g., MAC-TC-1684), first resolve it to numeric ID using FETCH_TEST_CASES 3. Version defaults to 1 if not specified 4. Provides version-specific metadata and history

Get detailed test case steps for a specific test case by numeric ID

Toolset: Test Cases

Parameters:

• projectKey (string): Project key - unique identifier for the project (default: "default")

• id (number) required: Test Case numeric ID (required for fetching steps or version details). Accepts a string or number. This is the internal numeric identifier, not the entity key like 'MAC-TC-1684'. You can get this ID from test case search results.

• version (number): Test Case version number (optional, defaults to 1). This is the internal numeric identifier for the version.

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

Output Description: JSON object with array of test steps including step description, expected result, and order

Use Cases: 1. Get step-by-step instructions with expected results 2. Retrieve test case execution procedure for manual runs 3. Export or display detailed test steps for documentation 4. Fetch steps before automation mapping

Examples:

1. Get steps for test case ID 123

{
  "id": 123
}

Expected Output: Detailed steps with actions and expected results for test case 123

Hints: 1. Requires numeric ID, not entityKey 2. If user provides entityKey (e.g., MAC-TC-1684), resolve it first via FETCH_TEST_CASES to get the numeric ID 3. Version defaults to 1 if not specified 4. Use pagination for test cases with many steps

Get execution records for a specific test case by numeric ID, including Test Run UDF values. ALWAYS present results as a unified table: Test Suite Key | Test Suite Name | Release | Cycle | Platform | Executed Version | Execution Status | <UDF Label columns…>. NEVER show a separate type+value UDF breakdown — always combine identification fields and UDF values in one table per execution row.

Toolset: Test Cases

Parameters:

• projectKey (string): Project key - unique identifier for the project (default: "default")

• tcid (number) required: Test Case numeric ID. CRITICAL: the parameter name is 'tcID' — do NOT use 'testCaseId', 'testCaseID', 'tcId', or other variants. Accepts a string or number. This is the internal numeric identifier, not the entity key like 'MAC-TC-1684'. You can get this ID from test case search results or by using filters.

• tcversion (number): Test Case version number (optional, defaults to 1). This is the internal numeric identifier for the version.

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

• scope (string): Scope of the operation - defines the context for data retrieval. Common values: 'project' (default), 'folder', 'release', 'cycle'. Applies to any entity type being fetched or operated upon. (default: "project")

• filter (string): Filter criteria as JSON string (default '[]') (default: "[]")

Output Description: JSON object with executions array. Each execution record ALWAYS contains these mandatory identification fields: 'tsEntityKey' (Test Suite Key, e.g. 'MAC-TS-42'), 'testsuiteName' (Test Suite Name), 'releaseName' (Release), 'cycleName' (Cycle), 'platform' (Platform/environment), 'executedVersion' (Executed Version of the test case), 'executionStatus' (Execution Status label), 'tcRunID' (numeric Test Run ID), and 'testRunUdfs' (array of objects each with name, label, fieldID, fieldType, value — use 'label' for display headers, null if not set). ALL project-defined UDF fields are always included, even those with no value. Top-level 'hasTcRunUdf' flag indicates whether the project has Test Run UDFs configured. When false, a 'testRunUdfNote' field provides a professional explanation instead.

Use Cases: 1. Get execution history for a specific test case 2. Retrieve test case execution results for reporting 3. Filter executions by test suite, platform, or execution status 4. Get execution data for test case analysis 5. Monitor test case execution trends over time 6. Filter executions by release, cycle, or execution date 7. Get execution details for specific test case versions 8. Audit test execution history for compliance 9. Analyze test case execution performance across different environments 10. Track test execution by specific users or teams 11. Fetch Test Run UDF values for a specific test case's execution records 12. Inspect custom metadata captured during test execution via Test Run UDFs 13. Check whether the project has Test Run UDFs configured (hasTcRunUdf flag)

Examples:

1. Get all executions for test case ID 1223922

{
  "tcid": 1223922
}

Expected Output: Present as ONE unified table — never as a separate type+value UDF breakdown. Example: | Test Suite Key | Test Suite Name | Release | Cycle | Platform | Executed Version | Execution Status | Tested By | Environments UDF | Execution Type | | MAC-TS-42 | Regression Suite | R1 | Sprint1| Chrome | v1 | Passed | varis | chrome, edge, safari | Functional | | MAC-TS-42 | Regression Suite | R1 | Sprint1| Firefox | v2 | Failed | john | firefox | Regression | Columns in order: Test Suite Key (tsEntityKey) | Test Suite Name (testsuiteName) | Release (releaseName) | Cycle (cycleName) | Platform (platform) | Executed Version (executedVersion) | Execution Status | then one column per UDF label. Use the UDF 'label' as column header. Show null UDF values as '-'.

2. Get executions for specific test case version

{
  "tcid": 1223922,
  "tcversion": 2
}

Expected Output: Execution records for version 2 of the test case

3. Filter executions by test suite and platform

{
  "tcid": 1223922,
  "filter": "[{\"value\":\"Sample Test Suite\",\"type\":\"string\",\"field\":\"testSuiteName\"},{\"value\":[12345],\"type\":\"list\",\"field\":\"platformID\"}]"
}

Expected Output: Filtered execution records matching test suite and platform criteria

4. Filter executions by execution status

{
  "tcid": 1223922,
  "filter": "[{\"value\":[\"PASS\"],\"type\":\"list\",\"field\":\"executionStatus\"}]"
}

Expected Output: Execution records with PASS status only

5. Filter executions by release and cycle

{
  "tcid": 1223922,
  "filter": "[{\"value\":[55178],\"type\":\"list\",\"field\":\"release\"},{\"value\":[111577],\"type\":\"list\",\"field\":\"cycle\"}]"
}

Expected Output: Execution records filtered by specific release and cycle

6. Filter executions by date range

{
  "tcid": 1223922,
  "filter": "[{\"value\":\"2024-01-01\",\"type\":\"date\",\"field\":\"executedDate\",\"comparison\":\"gt\"},{\"value\":\"2024-12-31\",\"type\":\"date\",\"field\":\"executedDate\",\"comparison\":\"lt\"}]"
}

Expected Output: Execution records within the specified date range

7. Filter executions by user

{
  "tcid": 1223922,
  "filter": "[{\"value\":[\"john.doe\"],\"type\":\"list\",\"field\":\"executedBy\"}]"
}

Expected Output: Execution records executed by specific user

8. Fetch Test Run UDF values for all executions of test case ID 41571999

{
  "tcid": 41571999
}

Expected Output: Present as ONE unified table combining identification fields and UDF values — never a separate type+value breakdown. Example: | Test Suite Key | Test Suite Name | Release | Cycle | Platform | Executed Version | Execution Status | Tested By | Environments UDF | Execution Type | Country | | MAC-TS-42 | Login Suite | R1 | Sprint1 | Chrome | v1 | Passed | varis | chrome, edge, safari | Functional | India > i3 | UDF column headers use the UDF 'label' (not raw field key). Null values shown as '-'.

9. Check if project has Test Run UDFs — response includes hasTcRunUdf flag

{
  "tcid": 1223922
}

Expected Output: Response contains hasTcRunUdf: true (UDFs present, testRunUdfs populated) or hasTcRunUdf: false (no UDFs configured, testRunUdfNote explains this)

Hints: 1. === MANDATORY RESPONSE FORMAT — READ THIS BEFORE RENDERING ANY OUTPUT === 2. 3. PIVOT RULE — CRITICAL: 4. The 'testRunUdfs' field on each execution is an array of { name, label, fieldID, fieldType, value }. 5. You MUST pivot this array into TABLE COLUMNS — do NOT render it as rows. 6. → Each testRunUdfs[i].label = a column header in the unified table 7. → Each testRunUdfs[i].value = the cell value for that execution's row 8. → testRunUdfs[i].fieldType = INTERNAL METADATA — NEVER show this as a column 9. → testRunUdfs[i].fieldID = INTERNAL METADATA — NEVER show this as a column 10. 11. FORBIDDEN PATTERNS — NEVER do any of these: 12. ❌ Do NOT render a separate sub-table (UDF Label | Type | Value) per execution 13. ❌ Do NOT show 'Type' or 'fieldType' as a visible column 14. ❌ Do NOT group output by tcRunID with individual breakdowns beneath each 15. ❌ Do NOT show raw UDF field keys (e.g. 'TRString', '8260LUP') as headers — use 'label' 16. 17. REQUIRED OUTPUT — ONE unified table, all executions as rows: 18. | Test Suite Key | Test Suite Name | Release | Cycle | Platform | Executed Version | Execution Status | <UDF Label 1> | <UDF Label 2> | ... | 19. |----------------|-----------------|---------|-------|----------|------------------|------------------|---------------|---------------|-----| 20. | MAC-TS-42 | Login Suite | R1 | S1 | Chrome | v1 | Passed | varis | chrome, edge | ... | 21. 22. MANDATORY COLUMNS (always first, in this order): 23. 1. Test Suite Key → tsEntityKey (e.g. 'MAC-TS-42') 24. 2. Test Suite Name → testsuiteName (test suite display name) 25. 3. Release → releaseName 26. 4. Cycle → cycleName 27. 5. Platform → platform 28. 6. Executed Version → executedVersion 29. 7. Execution Status → executionStatus 30. 8. Tested By → testedBy/executedBy when present 31. 9+. One column per UDF field — use testRunUdfs[i].label as header, testRunUdfs[i].value as cell. 32. 33. Null UDF values → show as '-'. If hasTcRunUdf is false, show columns 1-8 only. 34. UDF DATA SOURCE — THIS TOOL IS SELF-CONTAINED: 35. This tool automatically calls Test Run UDF metadata once (project-wide) and parses the udfjson field from each execution row. 36. The 'testRunUdfs' array in every execution record already contains ALL configured UDF fields — including fields with no value (null). 37. DO NOT call 'Fetch Test Run UDF Values' after this tool for test case executions — that tool uses GET_TESTCASE_RUNS_BY_TESTSUITE_RUN which is for test suite runs, not test case executions. 38. NEVER chain 'Fetch Test Run UDF Values' when the user asks for UDF values of test case executions — use testRunUdfs from THIS response directly. 39. === END MANDATORY RESPONSE FORMAT === 40. 41. This API requires a numeric tcid parameter, not entity key 42. If user provides entityKey (e.g., MAC-TC-1684), first call FETCH_TEST_CASES with filter on entityKeyId to resolve the tcid 43. After resolving entityKey → tcid, call this tool with the resolved numeric tcid 44. tcversion parameter is optional - omit to get executions for all versions 45. 46. CRITICAL WORKFLOW FOR LINKED ISSUES: When user asks 'fetch linked issues of test case [ID]' or 'linked issues of execution': 47. YOU MUST FIRST get the execution data using this tool to extract tcRunID before fetching issues! 48. 49. COMPLETE WORKFLOW FOR TEST CASE → LINKED ISSUES: 50. STEP 1: Resolve Test Case ID (if needed) - Use FETCH_TEST_CASES if user provides entity key 51. STEP 2: Fetch Test Case Executions (THIS TOOL) - Input: tcid, Extract: data[].tcRunID values 52. STEP 3: Fetch Linked Issues - Tool: FETCH_LINKED_ISSUES_BY_TESTCASE_RUN, Input: entityId = tcRunID 53. 54. ID MAPPING CRITICAL UNDERSTANDING: 55. - tcid/tcID = Test Case ID (for getting execution data with this tool) 56. - tcRunID = Test Case Run/Execution ID (THIS is entityId for linked issues API) 57. - entityId = tcRunID (what the linked issues API actually needs) 58. 59. NEVER USE tcid DIRECTLY as entityId for linked issues! 60. ALWAYS get tcRunID from executions and use THAT as entityId! 61. 62. EXAMPLE RESPONSE STRUCTURE FROM THIS TOOL: 63. { "data": [{ "tcRunID": 58312120, "testSuiteName": "Suite 1", "executionStatus": "PASS", "testRunUdfs": [...] }] } 64. → Use tcRunID (58312120) as entityId for linked issues API 65. 66. FILTER CAPABILITIES: Support extensive filtering by test suite, platform, status, user, release, cycle, dates, and archive status 67. FILTER FIELDS: testSuiteName (string), platformID (list), executionStatus (list), executedBy (list), project (list), release (list), cycle (list), executedDate (date with comparison), isPlatformArchived (list), isTestSuiteArchived (list), executedVersion (numeric) 68. DATE FILTERING: Use 'gt' (greater than) and 'lt' (less than) comparisons for executedDate field 69. EXECUTION STATUS: Common values include 'PASS', 'FAIL', 'BLOCKED', 'NOT_EXECUTED', 'WIP' (verify with your QMetry instance) 70. PLATFORM/SUITE ARCHIVE: Use [1,0] for both archived and non-archived, [1] for archived only, [0] for active only 71. Multiple filter conditions are combined with AND logic 72. Use pagination for large execution result sets (start, page, limit parameters) 73. Get platform IDs from FETCH_PLATFORMS tool and release/cycle IDs from FETCH_RELEASES_AND_CYCLES tool 74. This tool is essential for test execution reporting, trend analysis, and compliance auditing 75. Execution data includes timestamps, user information, environment details, and test results 76. Use scope parameter to define retrieval context (project, folder, release, cycle) 77. 78. TEST RUN UDF SUPPORT: 79. This tool automatically fetches UDF metadata (project-wide, one call for all executions) and enriches each execution record. 80. ALL project-defined Test Run UDF fields are returned for every execution — including fields with no value (value: null). 81. HTML is stripped from rich text (LARGETEXT) UDF field values for clean output. 82. Each execution's 'testRunUdfs' is an array of objects: 83. testRunUdfs: [ 84. { "name": "8260LUP", "label": "Lookup Field", "fieldID": 228563, "fieldType": "LOOKUPLIST", "value": "l1" }, 85. { "name": "TRString", "label": "TR String", "fieldID": 229241, "fieldType": "STRING", "value": "dsf" }, 86. { "name": "notes_run", "label": "Notes Run", "fieldID": 229242, "fieldType": "LARGETEXT", "value": null }, 87. { "name": "cascade_vK", "label": "Cascade VK", "fieldID": 229426, "fieldType": "CASCADINGLIST", "value": { "child": "qq", "parent": "vkc" } } 88. ] 89. Use 'fieldID' from testRunUdfs entries when calling 'Bulk Update Test Run UDFs'. 90. 91. hasTcRunUdf FLAG — IMPORTANT: 92. The response contains a 'hasTcRunUdf' boolean flag at the top level. 93. hasTcRunUdf: true → Project has Test Run UDFs configured; each execution record includes 'testRunUdfs' array with all fields. 94. hasTcRunUdf: false → Project has NO Test Run UDFs configured. 95. When hasTcRunUdf is false, the response includes a 'testRunUdfNote' field with a professional explanation. 96. Inform the user: 'No Test Run UDFs are configured for this project. Contact a project administrator to set up Test Run UDF fields.' 97. NEVER attempt to read testRunUdfs from records when hasTcRunUdf is false — the field will not be present.

Fetch test case steps including UDF field values via viewColumns endpoint

Toolset: Test Cases

Parameters:

• projectKey (string): Project key - unique identifier for the project (default: "default")

• tcID (number) required: Test Case numeric ID. CRITICAL: the parameter name is 'tcID' — do NOT use 'testCaseId', 'testCaseID', 'tcId', or other variants. Accepts a string or number. This is the internal numeric identifier, not the entity key like 'MAC-TC-1684'. You can get this ID from test case search results or by using filters.

• viewId (number): ViewId for test cases - SYSTEM AUTOMATICALLY RESOLVES THIS. Leave empty unless you have a specific viewId. System will fetch project info using the projectKey and extract latestViews.TC.viewId automatically.

• version (number): Test Case version number (optional, defaults to 1). This is the internal numeric identifier for the version.

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

Output Description: JSON object with data array (steps with UDF values), filterTemplate (UDF field definitions), columns (visible/hidden column config), total count, and viewId

Use Cases: 1. Get step UDF field values for a test case 2. Retrieve steps with custom fields before updating step UDFs 3. Inspect step-level UDF data for reporting

Examples:

1. Fetch steps with UDF values for test case ID 112768054

{
  "tcID": 112768054
}

Expected Output: Steps with UDF object containing field values, ID_ arrays for lookup IDs, UDF_ prefixed values, filterTemplate with UDF field definitions

Hints: 1. Response includes 'filterTemplate' array listing all UDF fields with their fieldType and udfmID 2. UDF values in each step row: UDF_ = display value, UDF_ID_ = numeric IDs 3. Step UDF object also has ID_ for lookup IDs 4. LOOKUPLIST: id = UDF_ID_, display = UDF_ 5. MULTILOOKUPLIST: ids = UDF_ID_ (array), display = UDF_ 6. CASCADINGLIST: parent = UDF_ID_[0], child = UDF_ID_[1] 7. viewId auto-resolved from project info if not provided

Link one or more defects/issues to a test case by entityKey and issue IDs.

Toolset: Test Cases

Parameters:

• tcID (string) required: EntityKey of the Test Case to link issues to (e.g. '8d7b-TC-63'). CRITICAL: the parameter name is 'tcID' — do NOT use 'testCaseId' or 'tcId'.

• dfIDs (array) required: Array of numeric defect/issue IDs to link to the test case (e.g. [2039, 2038, 2037]).

Output Description: JSON object with success status and linkage details.

Use Cases: 1. Link defects/issues to a test case for traceability 2. Bulk link multiple issues to a single test case 3. Automate defect coverage mapping

Examples:

1. Link issues to test case 8d7b-TC-63

{
  "tcID": "8d7b-TC-63",
  "dfIDs": [
    2039,
    2038,
    2037,
    1528
  ]
}

Expected Output: Issues linked to test case 8d7b-TC-63 successfully.

Hints: 1. To get the tcID, call the 'Fetch Test Cases' tool and use data[].entityKey. 2. dfIDs must be an array of numeric issue/defect IDs — resolve them using the 'Fetch Defects or Issues' tool. 3. If the user provides a test case entityKey (e.g., 8d7b-TC-63), use it directly as tcID. 4. CRITICAL: the parameter name is 'tcID' — do NOT use 'testCaseId' or 'tcId'. 5. CRITICAL: the parameter name is 'dfIDs' — do NOT use 'issueIds' or 'defectIds'.

Create a new requirement in QMetry with metadata and release/cycle mapping.

Toolset: Requirements

Parameters:

• name (string) required: Requirement name (required).

• priority (number): Priority ID of the requirement.

• component (array): Component (Label) IDs associated with the requirement.

• requirementOwner (number): Owner ID of the requirement.

• requirementState (number): State ID of the requirement.

• releaseCycleMapping (array): Release/cycle mapping for the requirement.

• description (string): Description of the requirement.

• associateRelCyc (boolean): Whether to associate the release/cycle mapping.

• rqFolderId (string): Requirement folder ID - SYSTEM AUTOMATICALLY RESOLVES THIS. Leave empty unless you have a specific folder ID. System will fetch project info using the projectKey and extract rootFolders.RQ.id automatically. Manual folder ID only needed if you want to target a specific sub-folder.

• scope (string): Scope of the requirement, usually 'project'. (default: "project")

• udfFields (record<string, union>): Flat UDF field values. Keys = UDF field names from 'Fetch UDF Layout'. Values depend on fieldTypeName: STRING/LARGETEXT: string, NUMBER: number, DATETIMEPICKER: date string ('14-08-2026'), LOOKUPLIST: numeric ID, MULTILOOKUPLIST: array of IDs [101, 102], CASCADINGLIST: { parent: 101, child: 102 }. Call 'Fetch UDF Layout' with entityType + pageName='ADD' to discover available fields and list option IDs.

Output Description: JSON object containing the new requirement ID, summary, and creation metadata.

Use Cases: 1. Create a basic requirement with just a name 2. Add detailed metadata like priority, component, and description to a requirement 3. Associate a requirement with a specific release/cycle for planning 4. Set requirementOwner and requirementState using valid IDs from project info 5. Create a requirement in a specific folder using rqFolderId 6. Set custom fields (UDFs) values on the new requirement

Examples:

1. Create a requirement in the root folder (auto-resolved)

{
  "name": "New login requirement"
}

Expected Output: Requirement created in the root requirement folder with ID and summary details

2. Create a requirement with metadata

{
  "name": "New login requirement",
  "priority": 688864,
  "component": [
    689030
  ],
  "requirementOwner": 8,
  "requirementState": 688912,
  "description": "Users must be able to log in with SSO.",
  "associateRelCyc": true,
  "releaseCycleMapping": [
    {
      "release": 1628,
      "cycle": [
        1839,
        1840
      ],
      "version": 1
    }
  ]
}

Expected Output: Requirement created with metadata. Example uses: priority=688864, component=[689030], requirementOwner=8, requirementState=688912 — resolve these IDs from project info's customListObjs before use.

Hints: 1. 'name' is the only mandatory field — sets the requirement's title/summary. Every other field is optional. 2. 'description' is a free-text field (supports HTML) for detailed requirement information. 3. 'component' is an array of Component (Label) IDs — resolve names to IDs from project info before use. 4. If rqFolderId is not provided, it will be auto-resolved to the root requirement folder using project info (rootFolders.RQ.id). 5. To get valid values for priority, component, requirementOwner (owner), requirementState (state), call the 'Admin/Get info Service' API (FETCH_PROJECT_INFO tool) and use the returned customListObjs IDs. 6. If the user provides a name instead of an ID for owner/state/priority/component, fetch project info, find the matching entry by name in the relevant customListObjs list, and use its ID. If not found, skip that field and tell the user it was omitted because the value wasn't available in the current project. 7. Release/cycle mapping is optional. If the user wants to associate a release and cycle, set associateRelCyc: true and provide releaseCycleMapping. 8. HARD GATE (not configurable): before creating, this tool checks project info for isExtTrackerConfigured, extTrackerType, and isRQConfigured. If the project has an external tracker configured (isExtTrackerConfigured=true) and isRQConfigured=true, and the tracker is Jira (extTrackerType=1) or Azure (extTrackerType=3), the create is refused with an error — do NOT retry or work around this. Tell the user requirements for this project must be created directly in the external system (Jira or Azure), then synced into QMetry. 9. 10. UDF (User Defined Fields) WORKFLOW FOR CREATE: 11. 1. Call 'Fetch UDF Layout' with entityType='RQ', pageName='ADD' to discover field names, types, and list option IDs. 12. IF listOptions[field.listName] is empty after Fetch UDF Layout, the tool already tried a metadata fallback. If STILL empty, ask the user to provide the option ID from the QMetry UI — do NOT guess numeric IDs. 13. 2. For LOOKUPLIST fields: pick one ID from listOptions[field.listName][].id. 14. 3. For MULTILOOKUPLIST fields: pick an array of IDs. 15. 4. For CASCADINGLIST fields: pick parent ID, then call 'Fetch Cascade Child Values' for child ID. Pass { parent: parentId, child: childId }. 16. 5. Pass all UDF values via 'udfFields' param: { fieldName: value }. 17. 6. Mandatory UDF fields (isMandatory=true) MUST be included or create will fail.

Update an existing QMetry requirement by rqId and rqVersionId.

Toolset: Requirements

Parameters:

• rqId (number) required: Requirement numeric ID (required). This is the internal numeric identifier, not the entity key like 'MAC-RQ-730'.

• rqVersionId (number) required: Requirement version ID (required for update).

• updateWithVersion (boolean): Pass 'true' to create a new version of the requirement instead of updating the existing version in place.

• name (string): Name of the requirement.

• description (string): Description of the requirement.

• component (array): Component (Label) IDs associated with the requirement.

• requirementOwner (number): Owner ID of the requirement.

• requirementState (number): State ID of the requirement.

• priority (number): Priority ID of the requirement.

• attachments (object): Attachment changes. ADD and REMOVE are both required arrays (use empty arrays for no change).

• udfFields (record<string, union>): Flat UDF field values. Keys = UDF field names from 'Fetch UDF Layout'. Values depend on fieldTypeName: STRING/LARGETEXT: string, NUMBER: number, DATETIMEPICKER: date string ('14-08-2026'), LOOKUPLIST: numeric ID, MULTILOOKUPLIST: array of IDs [101, 102], CASCADINGLIST: { parent: 101, child: 102 }. Call 'Fetch UDF Layout' with entityType + pageName='ADD' to discover available fields and list option IDs.

• UDF (record<string, object>): UDF wrapper required for update operations. Keys = UDF field names. Each value must include fieldID and value. Also set matching flat key in udfFields for the LOOKUPLIST Alias display. Example: { custom_text: { fieldID: 1001, value: 'new value' } }

Output Description: JSON object containing the updated requirement ID, summary, and update metadata.

Use Cases: 1. Update the name, description, priority, owner, state, or component of a requirement 2. Add or remove attachments on a requirement 3. Update custom field (UDF) values on a requirement 4. Create a new version of a requirement while updating it (updateWithVersion)

Examples:

1. Update the priority of a requirement

{
  "rqId": 2073,
  "rqVersionId": 2087,
  "updateWithVersion": false,
  "priority": 688865
}

Expected Output: Requirement priority updated successfully.

2. Update name, description, owner, and state

{
  "rqId": 2073,
  "rqVersionId": 2087,
  "name": "Updated login requirement",
  "description": "Users must be able to log in with SSO.",
  "requirementOwner": 8,
  "requirementState": 688912,
  "component": [
    689030
  ]
}

Expected Output: Requirement updated with new name, description, owner, state, and component.

Hints: 1. If the user provides an entityKey (e.g., MAC-RQ-730), first call 'Fetch Requirements' with a filter on entityKeyId to resolve rqId and rqVersionId. 2. updateWithVersion: pass 'true' to create a new version of the requirement instead of updating the current version in place. 3. To get valid values for priority, requirementOwner, requirementState, and component, call the 'Admin/Get info Service' API (FETCH_PROJECT_INFO tool) and use the returned customListObjs IDs. 4. If the user provides a name instead of an ID for owner/state/priority, fetch project info, find the matching entry by name in the relevant customListObjs list, and use its ID. If not found, skip that field and tell the user it was omitted because the value wasn't available in the current project. 5. attachments (if used) requires both ADD and REMOVE arrays — pass empty arrays when there is nothing to add or remove. 6. Only fields explicitly listed in this tool's parameters are supported — releaseCycleMapping and associateRelCyc are create-only and not supported here. 7. HARD GATE: before updating, this tool checks project info for isExtTrackerConfigured, extTrackerType, and isRQConfigured. If the project has an external tracker configured (isExtTrackerConfigured=true) and isRQConfigured=true, and the tracker is Jira (extTrackerType=1) or Azure (extTrackerType=3), the update is refused with an error — do NOT retry or work around this. Tell the user requirements for this project must be updated directly in the external system (Jira or Azure), then synced into QMetry. 8. 9. UDF (User Defined Fields) WORKFLOW FOR UPDATE: 10. 1. Call 'Fetch UDF Layout' with entityType='RQ', pageName='DETAIL' to get field names, fieldIDs (projectUserFieldID), and list option IDs. 11. IF listOptions[field.listName] is empty after Fetch UDF Layout, the tool already tried a metadata fallback. If STILL empty, ask the user to provide the option ID from the QMetry UI — do NOT guess numeric IDs. 12. 2. For LOOKUPLIST fields: pick one ID from listOptions[field.listName][].id. 13. 3. For MULTILOOKUPLIST fields: pick array of IDs; also pass alias flat key (e.g., fieldNameAlias: 'Option Label'). 14. 4. For CASCADINGLIST fields: pick parent ID + fetch child with 'Fetch Cascade Child Values'. Pass { parent: parentId, child: childId }. 15. 5. Pass BOTH 'udfFields' (flat root values) AND 'UDF' wrapper (with fieldID) — both required for update. Example: udfFields: { rq_field: 'value' }, UDF: { rq_field: { fieldID: 2001, value: 'value' } } 16. 6. Mandatory UDF fields (isMandatory=true) MUST be included.

Fetch QMetry requirements - automatically handles viewId resolution based on project

Toolset: Requirements

Parameters:

• projectKey (string): Project key - unique identifier for the project (default: "default")

• viewId (number): ViewId for requirements - SYSTEM AUTOMATICALLY RESOLVES THIS. Leave empty unless you have a specific viewId. System will fetch project info using the projectKey and extract latestViews.RQ.viewId automatically.

• folderPath (string): Folder path for requirements - SYSTEM AUTOMATICALLY SETS TO ROOT. Leave empty unless you want specific folder. System will automatically use empty string "" (root directory). Only specify if user wants specific folder like "Automation/Regression". (default: "")

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

• scope (string): Scope of the operation - defines the context for data retrieval. Common values: 'project' (default), 'folder', 'release', 'cycle'. Applies to any entity type being fetched or operated upon. (default: "project")

• getSubEntities (boolean): Whether to include sub-entities.

• hideEmptyFolders (boolean): Whether to hide empty folders.

• folderSortColumn (string): Folder sort column (default 'name')

• folderSortOrder (string): Folder sort order (ASC or DESC)

• isJiraFilter (boolean): 'false' if using qmetry filter (default: false)

• filterType (enum): Pass 'QMETRY' or 'JIRA' (default: "QMETRY")

• filter (string): Filter criteria as JSON string (default '[]') (default: "[]")

• udfFilter (string): User-defined field filter as JSON string (default '[]') (default: "[]")

• sort (string): Sort Records - refer json schema, Possible property - name, entityKey, associatedVersion, priorityAlias, createdDate, createdByAlias, updatedDate, updatedByAlias, requirementStateAlias, linkedTcCount, linkedDfCount, attachmentCount, createdSystem, owner (default: "[{"property":"name","direction":"ASC"}]")

Output Description: JSON object with 'data' array containing requirements and pagination info

Use Cases: 1. List all requirements in a project 2. Search for specific requirements using filters 3. Browse requirements in specific folders 4. Get paginated requirement results 5. Filter requirements by name or properties 6. Get requirement metadata for test planning

Examples:

1. Get all requirements from default project - system will auto-fetch viewId

{}

Expected Output: List of requirements from default project with auto-resolved viewId

2. Get all requirements from UT project - system will auto-fetch UT project's viewId

{
  "projectKey": "UT"
}

Expected Output: List of requirements from UT project using UT's specific RQ viewId

3. Search for specific requirements by entity key

{
  "projectKey": "MAC",
  "filter": "[{\"type\":\"string\",\"value\":\"MAC-RQ-123\",\"field\":\"entityKeyId\"}]"
}

Expected Output: Filtered requirements matching the entity key criteria

4. Search for multiple requirements by comma-separated entity keys

{
  "projectKey": "MAC",
  "filter": "[{\"type\":\"string\",\"value\":\"MAC-RQ-123,MAC-RQ-456,MAC-RQ-789\",\"field\":\"entityKeyId\"}]"
}

Expected Output: Requirements matching any of the specified entity keys

5. Filter requirements by state (e.g., Open, Approved)

{
  "projectKey": "MAC",
  "filter": "[{\"type\":\"string\",\"value\":\"Open\",\"field\":\"requirementStateAlias\"}]"
}

Expected Output: Requirements with 'Open' state

6. Filter requirements by priority

{
  "projectKey": "MAC",
  "filter": "[{\"type\":\"string\",\"value\":\"High\",\"field\":\"priorityAlias\"}]"
}

Expected Output: Requirements with 'High' priority

7. Filter requirements by archive status

{
  "filter": "[{\"value\":[1,0],\"type\":\"list\",\"field\":\"isArchived\"}]"
}

Expected Output: List of requirements filtered by archive status (archived and non-archived)

8. Get only archived requirements

{
  "filter": "[{\"value\":[1],\"type\":\"list\",\"field\":\"isArchived\"}]"
}

Expected Output: List of only archived requirements

9. Sort requirements by name in ascending order

{
  "projectKey": "MAC",
  "sort": "[{\"property\":\"name\",\"direction\":\"ASC\"}]"
}

Expected Output: Requirements sorted alphabetically by name

10. Sort requirements by creation date (newest first)

{
  "projectKey": "MAC",
  "sort": "[{\"property\":\"createdDate\",\"direction\":\"DESC\"}]"
}

Expected Output: Requirements sorted by creation date, newest first

11. Sort requirements by entity key

{
  "projectKey": "MAC",
  "sort": "[{\"property\":\"entityKey\",\"direction\":\"ASC\"}]"
}

Expected Output: Requirements sorted by entity key (MAC-RQ-1, MAC-RQ-2, etc.)

12. Sort requirements by linked test case count

{
  "projectKey": "MAC",
  "sort": "[{\"property\":\"linkedTcCount\",\"direction\":\"DESC\"}]"
}

Expected Output: Requirements sorted by number of linked test cases, highest first

13. Complex filter: Requirements by owner with specific state

{
  "projectKey": "MAC",
  "filter": "[{\"type\":\"string\",\"value\":\"john.doe\",\"field\":\"owner\"},{\"type\":\"string\",\"value\":\"Approved\",\"field\":\"requirementStateAlias\"}]"
}

Expected Output: Requirements owned by john.doe with 'Approved' state

14. Multi-field sort: Priority first, then creation date

{
  "projectKey": "MAC",
  "sort": "[{\"property\":\"priorityAlias\",\"direction\":\"DESC\"},{\"property\":\"createdDate\",\"direction\":\"ASC\"}]"
}

Expected Output: Requirements sorted by priority (High to Low), then by creation date (oldest first)

15. Filter requirements by specific release and cycle

{
  "projectKey": "MAC",
  "filter": "[{\"value\":[55178],\"type\":\"list\",\"field\":\"release\"},{\"value\":[111577],\"type\":\"list\",\"field\":\"cycle\"}]"
}

Expected Output: Requirements associated with Release 8.12 (ID: 55178) and Cycle 8.12.1 (ID: 111577)

16. Filter requirements by release only

{
  "projectKey": "MAC",
  "filter": "[{\"value\":[55178],\"type\":\"list\",\"field\":\"release\"}]"
}

Expected Output: All requirements associated with Release 8.12 (ID: 55178)

Hints: 1. CRITICAL WORKFLOW: Always use the SAME projectKey for both project info and requirement fetching 2. Step 1: If user specifies projectKey (like 'UT', 'MAC'), use that EXACT projectKey for project info 3. Step 2: Get project info using that projectKey, extract latestViews.RQ.viewId 4. Step 3: Use the SAME projectKey and the extracted RQ viewId for fetching requirements 5. Step 4: If user doesn't specify projectKey, use 'default' for both project info and requirement fetching 6. NEVER mix project keys - if user says 'MAC project', use projectKey='MAC' for everything 7. For search by requirement key (like MAC-RQ-123), use filter: '[{"type":"string","value":"MAC-RQ-123","field":"entityKeyId"}]' 8. For multiple entity keys, use comma-separated values: '[{"type":"string","value":"MAC-RQ-123,MAC-RQ-456","field":"entityKeyId"}]' 9. Use empty string '' as folderPath for root directory 10. Filter supports QMETRY and JIRA types - default is QMETRY 11. FILTER FIELDS: entityKeyId, name, requirementStateAlias, priorityAlias, owner, createdByAlias, updatedByAlias, createdSystem 12. SORT FIELDS: name, entityKey, associatedVersion, priorityAlias, createdDate, createdByAlias, updatedDate, updatedByAlias, requirementStateAlias, linkedTcCount, linkedDfCount, attachmentCount, createdSystem, owner 13. SORT DIRECTIONS: ASC (ascending), DESC (descending) 14. Multiple filters: Use array with multiple objects for AND conditions 15. Multiple sort criteria: Use array with multiple objects, first takes priority 16. Filter format: [{'type':'string','value':'filterValue','field':'fieldName'}] 17. Sort format: [{'property':'fieldName','direction':'ASC|DESC'}] 18. RELEASE/CYCLE FILTERING: Use release and cycle IDs from fetch_releases_and_cycles tool 19. For specific release: '[{"value":[releaseId],"type":"list","field":"release"}]' 20. For specific cycle: '[{"value":[cycleId],"type":"list","field":"cycle"}]' 21. For release AND cycle: '[{"value":[releaseId],"type":"list","field":"release"},{"value":[cycleId],"type":"list","field":"cycle"}]' 22. Example: Release 8.12 (ID: 55178) + Cycle 8.12.1 (ID: 111577) = filter with both IDs

Get detailed information for a specific QMetry requirement by numeric ID

Toolset: Requirements

Parameters:

• projectKey (string): Project key - unique identifier for the project (default: "default")

• id (number) required: Requirement numeric ID (required for fetching specific requirement details). This is the internal numeric identifier, not the entity key like 'MAC-RQ-730'. You can get this ID from requirement search results or by using filters.

• version (number) required: Requirement version number (required for fetching specific requirement version details). This is the internal numeric identifier for the version.

Output Description: JSON object with requirement details including ID, key, summary, description, status, and all metadata

Use Cases: 1. Get requirement details by numeric ID 2. Retrieve requirement metadata for reporting 3. Get requirement summary and properties 4. Fetch requirement details before linking or updating 5. Access requirement field values and custom fields 6. Get requirement version-specific information

Examples:

1. Get requirement details by numeric ID

{
  "id": 4791316,
  "version": 1
}

Expected Output: Detailed requirement information including summary, description, status, and all fields

Hints: 1. This API requires a numeric ID parameter, not entity key 2. If user provides entityKey (e.g., MAC-RQ-730), first call FETCH_REQUIREMENTS with a filter on entityKeyId to resolve the numeric ID 3. After resolving entityKey → numeric ID, call this tool with the resolved numeric ID 4. Version parameter is required - use 1 for the latest version unless user specifies otherwise 5. This tool provides complete requirement information including all custom fields 6. Use this tool to get detailed requirement information that's not available in the list view

Link one or more requirements to a test case by entityKey and version IDs.

Toolset: Requirements

Parameters:

• tcID (string) required: EntityKey of Testcase (e.g. 'COD-TC-29')

• tcVersionId (number) required: Test Case version number. This is the internal numeric identifier for the version.

• rqVersionIds (string) required: Comma-separated values of versionId of the Requirement (e.g. '236124,236125')

Output Description: JSON object with success status and linkage details.

Use Cases: 1. Link requirements to a test case for traceability 2. Bulk link multiple requirements to a single test case 3. Automate requirement coverage mapping

Examples:

1. Link requirements to test case VT-TC-26

{
  "tcID": "VT-TC-26",
  "tcVersionId": 5448515,
  "rqVersionIds": "5009939,5009937,4970699"
}

Expected Output: Requirements linked to test case VT-TC-26 successfully.

Hints: 1. To get the tcID, call the Testcase/Fetch List for Bulk Operation API and use data[].entityKey. 2. To get the tcVersionId, call the Testcase/Fetch Versions API and use data[].tcVersionID. 3. To get the rqVersionIds, call the requirement/List Versions API and use data[].rqVersionID. 4. If user provides requirement entityKey (e.g., VT-RQ-18), first call requirements list with a filter on entityKeyId to resolve the rqVersionIds 5. If user provides testcase entityKey (e.g., VT-TC-26), first call testcase list with a filter on entityKeyId to resolve the tcVersionId and tcID. 6. rqVersionIds must be a comma-separated string of requirement version IDs.

Get test cases that are linked (or not linked) to a specific requirement in QMetry

Toolset: Requirements

Parameters:

• projectKey (string): Project key - unique identifier for the project (default: "default")

• rqID (number) required: Requirement numeric ID (required for fetching specific requirement details). This is the internal numeric identifier, not the entity key like 'MAC-RQ-730'. You can get this ID from requirement search results or by using filters.

• getLinked (boolean): True to get only test cases that are linked with this requirement, false to get test cases which are not linked with this requirement. Defaults to true (get linked test cases). (default: true)

• showEntityWithReleaseCycle (boolean): True to list only test cases which have given release and cycle, false for all test cases regardless of release/cycle association. Defaults to false (show all). (default: false)

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

• tcFolderPath (string): Folder path to get test cases under specific folder. Use empty string "" for root folder or specify path like "/Sample Template". (default: "")

• releaseID (string): Filter test cases by release ID. Accepts a string or number. Get release IDs from FETCH_RELEASES_AND_CYCLES tool.

• cycleID (string): Filter test cases by cycle ID. Accepts a string or number. Get cycle IDs from FETCH_RELEASES_AND_CYCLES tool.

• filter (string): Filter criteria as JSON string (default '[]') (default: "[]")

• getSubEntities (boolean): Allow filter of sub-entities for requirement. (default: true)

• getColumns (boolean): True to get column information in response. (default: true)

Output Description: JSON object with test cases array, traceability information, and pagination metadata

Use Cases: 1. Get all test cases linked to a specific requirement for traceability analysis 2. Find test cases that are NOT linked to a requirement (gap analysis) 3. Verify requirement coverage by checking linked test cases 4. Impact analysis - see which test cases are affected when a requirement changes 5. Generate traceability matrix between requirements and test cases 6. Filter linked test cases by release, cycle, or other criteria 7. Audit requirement-test case relationships for compliance 8. Identify orphaned test cases or requirements without proper links 9. Plan test execution based on requirement-test case associations 10. Quality assurance - ensure all requirements have adequate test coverage

Examples:

1. Get all test cases linked to requirement ID 4791316

{
  "rqID": 4791316
}

Expected Output: List of test cases that are linked to requirement MAC-RQ-1011

2. Get test cases NOT linked to requirement (gap analysis)

{
  "rqID": 4791316,
  "getLinked": false
}

Expected Output: List of test cases that are NOT linked to requirement MAC-RQ-1011

3. Get linked test cases filtered by specific release

{
  "rqID": 4791316,
  "releaseID": "55178"
}

Expected Output: Linked test cases associated with Release 8.12 (ID: 55178)

4. Get linked test cases filtered by release and cycle

{
  "rqID": 4791316,
  "releaseID": "55178",
  "cycleID": "111577",
  "showEntityWithReleaseCycle": true
}

Expected Output: Linked test cases in Release 8.12 and Cycle 8.12.1

5. Get linked test cases from specific folder

{
  "rqID": 4791316,
  "tcFolderPath": "/Sample Template"
}

Expected Output: Linked test cases located in the '/Sample Template' folder

6. Search linked test cases by entity key

{
  "rqID": 4791316,
  "filter": "[{\"type\":\"string\",\"value\":\"MAC-TC-1684,MAC-TC-1685\",\"field\":\"entityKeyId\"}]"
}

Expected Output: Linked test cases matching specific entity keys

7. Filter linked test cases by priority

{
  "rqID": 4791316,
  "filter": "[{\"type\":\"list\",\"value\":[1,2],\"field\":\"priorityAlias\"}]"
}

Expected Output: Linked test cases with High or Medium priority

8. Filter linked test cases by status

{
  "rqID": 4791316,
  "filter": "[{\"type\":\"list\",\"value\":[1,2],\"field\":\"testCaseStateAlias\"}]"
}

Expected Output: Linked test cases with Active or Review status

9. Filter linked test cases by test case type

{
  "rqID": 4791316,
  "filter": "[{\"type\":\"list\",\"value\":[1],\"field\":\"testCaseTypeAlias\"}]"
}

Expected Output: Linked functional test cases

10. Filter linked test cases by testing type (automation)

{
  "rqID": 4791316,
  "filter": "[{\"type\":\"list\",\"value\":[2],\"field\":\"testingTypeAlias\"}]"
}

Expected Output: Linked automated test cases

11. Get only parameterized linked test cases

{
  "rqID": 4791316,
  "filter": "[{\"type\":\"list\",\"value\":[1],\"field\":\"isParameterized\"}]"
}

Expected Output: Linked test cases that are parameterized (data-driven)

12. Filter linked test cases by archive status

{
  "rqID": 4791316,
  "filter": "[{\"type\":\"list\",\"value\":[0],\"field\":\"isArchived\"}]"
}

Expected Output: Active (non-archived) linked test cases

13. Search linked test cases by summary content

{
  "rqID": 4791316,
  "filter": "[{\"type\":\"string\",\"value\":\"login\",\"field\":\"summary\"}]"
}

Expected Output: Linked test cases with 'login' in their summary

14. Filter linked test cases by requirement version

{
  "rqID": 4791316,
  "filter": "[{\"type\":\"string\",\"value\":\"1\",\"field\":\"rqVersion\"}]"
}

Expected Output: Test cases linked to version 1 of the requirement

15. Complex filter: Active, high priority, automated test cases

{
  "rqID": 4791316,
  "filter": "[{\"type\":\"list\",\"value\":[0],\"field\":\"isArchived\"},{\"type\":\"list\",\"value\":[1],\"field\":\"priorityAlias\"},{\"type\":\"list\",\"value\":[2],\"field\":\"testingTypeAlias\"}]"
}

Expected Output: Active, high priority, automated test cases linked to requirement

Hints: 1. This API requires a numeric rqID parameter, not entity key 2. If user provides entityKey (e.g., MAC-RQ-1011), first call FETCH_REQUIREMENTS with filter on entityKeyId to resolve the numeric rqID 3. After resolving entityKey → rqID, call this tool with the resolved numeric rqID 4. TRACEABILITY WORKFLOW: Use this tool to establish requirement-test case traceability matrix 5. getLinked=true (default): Returns test cases that ARE linked to the requirement 6. getLinked=false: Returns test cases that are NOT linked to the requirement (useful for gap analysis) 7. showEntityWithReleaseCycle=true: Only show test cases that have the specified release and cycle 8. showEntityWithReleaseCycle=false (default): Show all test cases regardless of release/cycle 9. RELEASE/CYCLE FILTERING: Use string IDs, not numeric (e.g., releaseID: '55178', cycleID: '111577') 10. Get release/cycle IDs from FETCH_RELEASES_AND_CYCLES tool before filtering 11. tcFolderPath: Use empty string '' for root folder or specific path like '/Sample Template' 12. FILTER CAPABILITIES: Support same filters as regular test case listing 13. FILTER FIELDS: summary, rqVersion, priorityAlias, testCaseStateAlias, createdByAlias, testCaseTypeAlias, testingTypeAlias, release, cycle, isArchived, isParameterized, componentAlias, entityKeyId 14. PRIORITY IDs: Typically 1=High, 2=Medium, 3=Low (verify with your QMetry instance) 15. STATUS IDs: Typically 1=Active, 2=Review, 3=Deprecated (verify with your QMetry instance) 16. TYPE IDs: Typically 1=Functional, 2=Integration, 3=System (verify with your QMetry instance) 17. TESTING TYPE IDs: Typically 1=Manual, 2=Automated (verify with your QMetry instance) 18. PARAMETERIZED: 1=Yes (parameterized), 0=No (non-parameterized) 19. ARCHIVED: 1=Archived, 0=Active (non-archived) 20. Multiple filter conditions are combined with AND logic 21. For entity key search, use comma-separated values: 'MAC-TC-1,MAC-TC-2,MAC-TC-3' 22. This tool is crucial for compliance, traceability audits, and impact analysis 23. Use getColumns=true to get column metadata for better result interpretation 24. Pagination supported for large result sets (start, page, limit parameters)

Get requirements that are linked (or not linked) to a specific test case in QMetry

Toolset: Requirements

Parameters:

• projectKey (string): Project key - unique identifier for the project (default: "default")

• tcID (number) required: Test Case numeric ID. CRITICAL: the parameter name is 'tcID' — do NOT use 'testCaseId', 'testCaseID', 'tcId', or other variants. Accepts a string or number. This is the internal numeric identifier, not the entity key like 'MAC-TC-1684'. You can get this ID from test case search results or by using filters.

• getLinked (boolean): True to get only requirements that are linked with this test case, false to get requirements which are not linked with this test case. Defaults to true (get linked requirements). (default: true)

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

• rqFolderPath (string): Folder path for requirements - SYSTEM AUTOMATICALLY SETS TO ROOT. Leave empty unless you want specific folder. System will automatically use empty string "" (root directory). Only specify if user wants specific folder like "Automation/Regression". (default: "")

• filter (string): Filter criteria as JSON string (default '[]') (default: "[]")

Output Description: JSON object with requirements array, traceability information, and pagination metadata

Use Cases: 1. Get all requirements linked to a specific test case for traceability analysis 2. Find requirements that are NOT linked to a test case (gap analysis) 3. Verify test case coverage by checking linked requirements 4. Impact analysis - see which requirements are affected when a test case changes 5. Generate traceability matrix between test cases and requirements 6. Filter linked requirements by various criteria 7. Audit test case-requirement relationships for compliance 8. Identify orphaned requirements or test cases without proper links 9. Plan requirement validation based on test case-requirement associations 10. Quality assurance - ensure all test cases have proper requirement coverage

Examples:

1. Get all requirements linked to test case ID 594294

{
  "tcID": 594294
}

Expected Output: List of requirements that are linked to test case MAC-TC-1684

2. Get requirements NOT linked to test case (gap analysis)

{
  "tcID": 594294,
  "getLinked": false
}

Expected Output: List of requirements that are NOT linked to test case MAC-TC-1684

3. Get linked requirements from specific folder

{
  "tcID": 594294,
  "rqFolderPath": "/CodeSnippets"
}

Expected Output: Linked requirements located in the '/CodeSnippets' folder

4. Search linked requirements by entity key

{
  "tcID": 594294,
  "filter": "[{\"type\":\"string\",\"value\":\"MAC-RQ-730,MAC-RQ-731\",\"field\":\"entityKeyId\"}]"
}

Expected Output: Linked requirements matching specific entity keys

5. Filter linked requirements by status

{
  "tcID": 594294,
  "filter": "[{\"type\":\"list\",\"value\":[1,2],\"field\":\"requirementStateAlias\"}]"
}

Expected Output: Linked requirements with Open or Approved status

6. Filter linked requirements by priority

{
  "tcID": 594294,
  "filter": "[{\"type\":\"list\",\"value\":[1],\"field\":\"priorityAlias\"}]"
}

Expected Output: Linked requirements with High priority

7. Filter linked requirements by archive status

{
  "tcID": 594294,
  "filter": "[{\"type\":\"list\",\"value\":[0],\"field\":\"isArchived\"}]"
}

Expected Output: Active (non-archived) linked requirements

8. Search linked requirements by name content

{
  "tcID": 594294,
  "filter": "[{\"type\":\"string\",\"value\":\"authentication\",\"field\":\"name\"}]"
}

Expected Output: Linked requirements with 'authentication' in their name

9. Filter linked requirements by test case version

{
  "tcID": 594294,
  "filter": "[{\"type\":\"string\",\"value\":\"1\",\"field\":\"tcVersion\"}]"
}

Expected Output: Requirements linked to version 1 of the test case

10. Filter linked requirements by release and cycle

{
  "tcID": 594294,
  "filter": "[{\"type\":\"list\",\"value\":[55178],\"field\":\"release\"},{\"type\":\"list\",\"value\":[111577],\"field\":\"cycle\"}]"
}

Expected Output: Linked requirements in Release 8.12 and Cycle 8.12.1

Hints: 1. This API requires a numeric tcID parameter, not entity key 2. If user provides entityKey (e.g., MAC-TC-1684), first call FETCH_TEST_CASES with filter on entityKeyId to resolve the numeric tcID 3. After resolving entityKey → tcID, call this tool with the resolved numeric tcID 4. TRACEABILITY WORKFLOW: Use this tool to establish test case-requirement traceability matrix 5. getLinked=true (default): Returns requirements that ARE linked to the test case 6. getLinked=false: Returns requirements that are NOT linked to the test case (useful for gap analysis) 7. rqFolderPath: Use empty string '' for root folder or specific path like '/CodeSnippets' 8. FILTER CAPABILITIES: Support same filters as regular requirement listing 9. FILTER FIELDS: name, entityKeyId, requirementStateAlias, priorityAlias, createdByAlias, tcVersion, release, cycle, isArchived, componentAlias 10. Multiple filter conditions are combined with AND logic 11. For entity key search, use comma-separated values: 'MAC-RQ-1,MAC-RQ-2,MAC-RQ-3' 12. This tool is crucial for compliance, traceability audits, and impact analysis 13. Pagination supported for large result sets (start, page, limit parameters) 14. Use this tool to verify that test cases properly cover requirements 15. Essential for requirement validation and test case completeness analysis

Create a new test suite in QMetry with metadata and release/cycle mapping.

Toolset: Test Suites

Parameters:

• parentFolderId (string): Test Suite parent folder ID - SYSTEM AUTOMATICALLY RESOLVES THIS. Leave empty unless you have a specific folder ID. System will fetch project info using the projectKey and extract rootFolders.TS.id automatically. Manual folder ID only needed if you want to target a specific sub-folder.

• name (string) required

• isAutomatedFlag (boolean)

• description (string)

• testsuiteOwner (number)

• testSuiteState (number)

• associateRelCyc (boolean)

• releaseCycleMapping (array): Release/cycle association for the test suite. CRITICAL SHAPE DIFFERENCE vs Test Case mapping: Test Suite uses: { releaseId: number, buildID: number } Test Case uses: { release: number, cycle: number[], version: number } — DO NOT use TC shape here. Set associateRelCyc=true when providing this array. Example: [{ releaseId: 92112, buildID: 130831 }]

• udfFields (record<string, union>): Flat UDF field values. Keys = UDF field names from 'Fetch UDF Layout'. Values depend on fieldTypeName: STRING/LARGETEXT: string, NUMBER: number, DATETIMEPICKER: date string ('14-08-2026'), LOOKUPLIST: numeric ID, MULTILOOKUPLIST: array of IDs [101, 102], CASCADINGLIST: { parent: 101, child: 102 }. Call 'Fetch UDF Layout' with entityType + pageName='ADD' to discover available fields and list option IDs.

Output Description: JSON object containing the new test suite ID, summary, and creation metadata.

Use Cases: 1. Create a basic test suite with just a name and folder 2. Add detailed metadata like description to a test suite 3. Associate test suite with specific release/cycle for planning 4. Set testsuiteOwner, testSuiteState, and other metadata using valid IDs from project info 5. Create test suites for isAutomatedFlag true or false for automated or manual types, default is false 6. Add test suite to a specific folder using parentFolderId 7. Map test suite to multiple cycles/releases and build ID

Examples:

1. Create a test suite in the root folder (auto-resolved)

{
  "name": "Demo Test Suite"
}

Expected Output: Test suite created in the root test suite folder with ID and summary details

2. Create a simple test suite in folder 102653

{
  "parentFolderId": "102653",
  "name": "Login Test Suite"
}

Expected Output: Test suite created with ID and summary details

3. Create a test suite with some details and metadata

{
  "parentFolderId": "113557",
  "isAutomatedFlag": false,
  "name": "Testsuite Summary",
  "description": "desc",
  "testsuiteOwner": 6963,
  "testSuiteState": 505035,
  "associateRelCyc": true,
  "releaseCycleMapping": [
    {
      "buildID": 18411,
      "releaseId": 10286
    }
  ]
}

Expected Output: Test suite created with details and metadata. Example uses: parentFolderId=113557 (MAC root TS folder from rootFolders.TS.id), testsuiteOwner=6963 (umang.savaliya from customListObjs.owner[index].id), testSuiteState=505035 (New from customListObjs.testSuiteState[index].id), releaseId=10286 (Air release from projects[index].releases[index].releaseID), buildID=18411 (Air Q1-19 cycle from projects[index].releases[index].builds[index].buildID)

Hints: 1. ╔══════════════════════════════════════════════════════════════════╗ 2. ║ STEP 0 — NON-NEGOTIABLE: Call 'Fetch UDF Layout' BEFORE create ║ 3. ╚══════════════════════════════════════════════════════════════════╝ 4. NEVER call 'Create Test Suite' without first calling 'Fetch UDF Layout' with entityType='TS', pageName='ADD'. 5. Skipping this step WILL cause 400 errors (CO.MANDATORY_FIELDS_MISSING) because mandatory fields and defaults are unknown. 6. This rule has NO exceptions — not even when the user only provided a name and nothing else. 7. 8. === MANDATORY PRE-CREATE CHECK (ALWAYS DO THIS FIRST) === 9. Before creating any test suite, call 'Fetch UDF Layout' with entityType='TS', pageName='ADD'. 10. Response keys use 'TS' — same structure as TC but scoped to test suite module. 11. 12. SYSTEM FIELDS mandatory check — use 'systemFields' array (from qmSDF.TS in newlayout): 13. Each entry: { name, label, fieldTypeName, isMandatory } 14. isMandatory=true (allowBlank=false) means field MUST have a value before creating. 15. 16. UDF FIELDS mandatory check — use 'fields' array (from qmUDF.TS in newlayout): 17. Each entry: { name, label, fieldTypeName, isMandatory, listName? } 18. isMandatory=true means field MUST have a value. 19. 20. DEFAULT VALUES — use 'defaultValues' object (from qmDefaultValue.TS in newlayout): 21. Shape: { fieldName: defaultValueId } e.g. { 'priority': 5232497, 'estimatedTime': 18305 } 22. RULE: isMandatory=true AND defaultValues[field.name] exists → auto-use default, do NOT ask user. 23. RULE: isMandatory=true AND no defaultValues entry → MUST ask user before creating. 24. RULE: isMandatory=false AND defaultValues entry exists → auto-apply if user didn't specify. 25. 26. ╔══════════════════════════════════════════════════════════════════════════╗ 27. ║ PRE-FLIGHT DEFAULT SWEEP — MANDATORY STEP BEFORE EVERY CREATE CALL ║ 28. ╚══════════════════════════════════════════════════════════════════════════╝ 29. After resolving mandatory fields, sweep ALL defaultValues entries: 30. For EACH key in defaultValues: 31. IF the user did not explicitly provide that field → add it to the payload using the default value. 32. This applies regardless of isMandatory — non-mandatory defaults MUST also be auto-applied. 33. Example: defaultValues = { priority: 5232497, estimatedTime: 18305 } 34. → user only said 'create a test suite named X' 35. → payload MUST include: priority=5232497, estimatedTime=18305 36. → WRONG to omit priority/estimatedTime just because they are not mandatory — they have defaults. 37. Skipping this sweep = missing fields in the created record = user-visible data loss. 38. ╚══════════════════════════════════════════════════════════════════════════╝ 39. 40. DECISION MATRIX: 41. | isMandatory | Has default | Action | 42. |-------------|-------------|-------------------------------------| 43. | true | YES | Auto-fill with default, no ask | 44. | true | NO | Ask user before creating | 45. | false | YES | Auto-fill with default — REQUIRED | 46. | false | NO | Skip if user didn't provide | 47. Only after ALL mandatory fields resolved AND default sweep complete → proceed with create. 48. === END MANDATORY PRE-CREATE CHECK === 49. 50. === ERROR RECOVERY: CO.MANDATORY_FIELDS_MISSING === 51. If create fails with error code 'CO.MANDATORY_FIELDS_MISSING', DO NOT give up. Auto-recover: 52. 1. Parse the 'MISSING_FIELDS' list from the error response (comma-separated field labels). 53. 2. Match each label against 'fields[].label' and 'systemFields[].label' from the Fetch UDF Layout response. 54. 3. For matched UDF fields: check 'listOptions[field.listName]' for valid option IDs. 55. 4. For matched system fields (e.g. 'Status'): check 'customListObjs.testSuiteState' from project info. 56. 5. If the field has a 'defaultValues' entry: auto-fill it silently. 57. 6. If no default exists: ask the user ONLY for the missing fields by label. 58. 7. Retry create with the resolved values added to the payload. 59. NEVER ask user to 'try again' manually — resolve and retry automatically. 60. === END ERROR RECOVERY === 61. 62. === DATE FORMAT CHECK (MANDATORY — EVERY CREATE REQUEST) === 63. ALWAYS call 'Fetch QMetry Project Info' before every create request — not only when the user explicitly mentions a date. 64. Any UDF field could be a DATETIMEPICKER. Wrong format causes QMetry to silently discard the field value (API returns success but value is NOT stored — no error). 65. STEP 1: From project info, read dateTimeFormatID (e.g. 3). 66. STEP 2: Find entry in dateTimeFormatNew where id === dateTimeFormatID → read its unique_value (e.g. 'yyyy-MM-dd'). 67. STEP 3: unique_value pattern: yyyy=4-digit year, MM=2-digit month (01-12), dd=2-digit day, MMM=3-letter month (Jan/Feb/...). 68. Example: id=1 → MM-dd-yyyy → '10-25-2000' | id=2 → dd-MM-yyyy → '25-10-2000' | id=3 → yyyy-MM-dd → '2000-10-25' | id=4 → dd-MMM-yyyy → '25-Oct-2000' 69. STEP 4: For EVERY DATETIMEPICKER field in the payload: parse any user-provided date and re-format it using the active unique_value pattern before sending. 70. NEVER assume a date format — always derive it from dateTimeFormatID. Wrong format = silent data loss. 71. === END DATE FORMAT CHECK === 72. 73. If parentFolderId is not provided, it will be auto-resolved to the root test suite folder using project info (rootFolders.TS.id). 74. To get valid values for testsuiteOwner, testSuiteState, etc., call the 'Admin/Get info Service' API (FETCH_PROJECT_INFO tool) and use the returned customListObjs IDs. 75. CRITICAL: For testsuiteOwner mapping - Call API 'Admin/Get info Service', from the response get value from customListObjs.owner[].id. Match the user by customListObjs.owner[].name. 76. If the user provides an owner name (testsuiteOwner), fetch project info, find the matching owner in customListObjs.owner[index].name or customListObjs.owner[index].uniqueLabel, and use its ID in the payload as testsuiteOwner. If the name is not found, skip the testsuiteOwner field (it is not required) and show a user-friendly message: 'Test suite created without owner, as given owner is not available in the current project.' 77. CRITICAL: For testSuiteState mapping - Call API 'Admin/Get info Service', from the response get value from customListObjs.testSuiteState[].id. Match the state by customListObjs.testSuiteState[].name. 78. If the user provides a test suite state name(testSuiteState), fetch project info, find the matching state in customListObjs.testSuiteState[index].name, and use its ID in the payload as testSuiteState. If the name is not found, skip the testSuiteState field (it is not required) and show a user-friendly message: 'Test suite created without test suite state, as given state is not available in the current project.' 79. parentFolderId is required; use the root folder ID from project info (rootFolders.TS.id) or a specific folder. 80. Release/cycle mapping is optional but useful for planning. 81. If the user wants to link or associate a release and cycle to the test suite, set associateRelCyc: true in the payload. 82. CRITICAL: For releaseCycleMapping.releaseId - Call API 'Release/List' (or use project info projects[].releases[].releaseID), from the response get value from data[].releaseID or projects[].releases[].releaseID. Match the release by name. 83. CRITICAL: For releaseCycleMapping.buildID - Call API 'Cycle/List' (or use project info projects[].releases[].builds[].buildID), from the response get value from data[].buildID or projects[].releases[].builds[].buildID. Match the build/cycle by name. 84. If the user provides a release name, map it to its ID from projects[].releases[].releaseID in the project info response, and use that ID as releaseId in releaseCycleMapping. 85. If the user provides a build/cycle name, map it to its ID from projects[].releases[].builds[].buildID in the project info response, and use that ID as buildID in releaseCycleMapping. 86. Example payload: releaseCycleMapping: [ { releaseId: , buildID: } ] 87. Example: For 'Air' release and 'Air Q1-19' cycle in MAC project, use releaseId: 10286 and buildID: 18411 88. LLM should ensure that provided release/cycle names or IDs exist in the current project before using them in the payload. If not found, skip and show a user-friendly message: 'Test suite created without release/cycle association, as given release/cycle is not available in the current project.' 89. All IDs (testSuiteState from customListObjs.testSuiteState[index].id, testsuiteOwner from customListObjs.owner[index].id, releaseId from projects.releases[index].releaseID, buildID from projects.releases.builds[index].buildID) must be valid for your QMetry instance. 90. If a custom field is mandatory, include it in the UDF object. 91. 92. UDF (User Defined Fields) WORKFLOW FOR CREATE: 93. 1. Call 'Fetch UDF Layout' with entityType='TS', pageName='ADD' to discover field names, types, and list option IDs. 94. IF listOptions[field.listName] is empty after Fetch UDF Layout, the tool already tried a metadata fallback. If STILL empty, ask the user to provide the option ID from the QMetry UI — do NOT guess numeric IDs. 95. 2. For LOOKUPLIST fields: pick one ID from listOptions[field.listName][].id. 96. 3. For MULTILOOKUPLIST fields: pick an array of IDs. 97. 4. For CASCADINGLIST fields: pick parent ID, then call 'Fetch Cascade Child Values' for child ID. Pass { parent: parentId, child: childId }. 98. 5. Pass all UDF values via 'udfFields' param: { fieldName: value }. 99. 6. Mandatory UDF fields (isMandatory=true) MUST be included or create will fail. 100. 101. ╔══════════════════════════════════════════════════════════════════╗ 102. ║ POST-CREATE MANDATORY: Link Platform to Test Suite ║ 103. ╚══════════════════════════════════════════════════════════════════╝ 104. AFTER every successful test suite creation, ALWAYS call 'Link Platforms to Test Suite'. 105. Reason: QMetry UI enforces platform association — test suites without a linked platform 106. are invalid for execution and will show validation errors in the UI. 107. STEP 1: Call 'Fetch Platforms' to get available platforms for the project. 108. STEP 2: If the user specified a platform, match by name and use its platformID. 109. If no platform was specified, use the first available non-archived platform. 110. STEP 3: Call 'Link Platforms to Test Suite' with qmTsId= and qmPlatformId=. 111. NEVER report the test suite as successfully created without completing this platform link step. 112. ╚══════════════════════════════════════════════════════════════════╝

Update an existing QMetry test suite by id(testsuite numeric id), with auto-resolution from entityKey.

Toolset: Test Suites

Parameters:

• id (number) required: Id of Test Suite to be updated (required)

• TsFolderID (number): Folder ID where Test Suite resides - SYSTEM AUTOMATICALLY RESOLVES THIS. Leave empty unless you have a specific folder ID. System will fetch project info using the projectKey and extract rootFolders.TS.id automatically. Manual folder ID only needed if you want to override the automatic resolution.

• entityKey (string) required: Entity Key of Test Suite to be updated (required)

• name (string): Name of the Test Suite

• description (string): Description of the Test Suite

• testsuiteOwner (number): Owner ID of the Test Suite

• testSuiteState (number): State of the Test Suite

• udfFields (record<string, union>): Flat UDF field values. Keys = UDF field names from 'Fetch UDF Layout'. Values depend on fieldTypeName: STRING/LARGETEXT: string, NUMBER: number, DATETIMEPICKER: date string ('14-08-2026'), LOOKUPLIST: numeric ID, MULTILOOKUPLIST: array of IDs [101, 102], CASCADINGLIST: { parent: 101, child: 102 }. Call 'Fetch UDF Layout' with entityType + pageName='ADD' to discover available fields and list option IDs.

• UDF (record<string, object>): UDF wrapper required for update. Keys = UDF field names. Each value must include fieldID (from 'Fetch UDF Layout' with pageName='DETAIL') and value.

Output Description: JSON object containing the new test suite ID, summary, and creation metadata.

Use Cases: 1. Update test suite summary (name) 2. Change owner, or state of a test suite 3. Bulk update using entityKey auto-resolution 4. Modify test suite description

Examples:

1. Update test suite summary (updated name)

{
  "id": 1505898,
  "entityKey": "VT-TS-7",
  "TsFolderID": 1644087,
  "name": "MAC Test11"
}

Expected Output: Test suite summary updated. Only 'name' field changed. Field IDs auto-resolved from project info. id(test suite numeric id) resolved from entityKey. TsFolderID auto-resolved. from the project info. info on rootFolders.TS.id.

2. Update state to Open and owner of the test suite

{
  "id": 1505898,
  "entityKey": "VT-TS-7",
  "TsFolderID": 1644087,
  "testSuiteState": 505036,
  "testsuiteOwner": 6963
}

Expected Output: State and owner updated. Example uses: testSuiteState=505036 (Open from customListObjs.testSuiteState[index].id), testsuiteOwner=6963 (umang.savaliya from customListObjs.owner[index].id). Field IDs auto-resolved from project info. id(test suite numeric id) resolved from entityKey. TsFolderID auto-resolved from the project info rootFolders.TS.id.

3. Update only description of the test suite

{
  "id": 1505898,
  "entityKey": "VT-TS-7",
  "TsFolderID": 1644087,
  "description": "Updated description for the test suite."
}

Expected Output: description updated only. Field IDs auto-resolved from project info. id(test suite numeric id) resolved from entityKey. TsFolderID auto-resolved. from the project info. info on rootFolders.TS.id.

Hints: 1. === DEFAULT VALUES — APPLY FOR ANY UNSET FIELD === 2. ALWAYS call 'Fetch UDF Layout' with entityType='TS', pageName='DETAIL' before updating. 3. defaultValues (from Fetch UDF Layout): { fieldName: defaultValueId } — sweep ALL entries. 4. For EACH key in defaultValues: if user did not explicitly provide that field → include it in payload with the default value. 5. This applies to non-mandatory fields too (e.g. testSuiteState). Omitting them = data loss. 6. systemFields (from qmSDF.TS): isMandatory=true fields must retain a valid value after update. 7. fields/UDF (from qmUDF.TS): isMandatory=true UDF fields must be included if being changed. 8. === END DEFAULT VALUES === 9. 10. === DATE FORMAT CHECK (MANDATORY — EVERY UPDATE REQUEST) === 11. ALWAYS call 'Fetch QMetry Project Info' before every update request — not only when the user explicitly mentions a date. 12. Any UDF field could be a DATETIMEPICKER. Wrong format causes QMetry to silently discard the field value (API returns success but value is NOT stored — no error). 13. STEP 1: From project info, read dateTimeFormatID (e.g. 3). 14. STEP 2: Find entry in dateTimeFormatNew where id === dateTimeFormatID → read its unique_value (e.g. 'yyyy-MM-dd'). 15. STEP 3: unique_value pattern: yyyy=4-digit year, MM=2-digit month (01-12), dd=2-digit day, MMM=3-letter month (Jan/Feb/...). 16. Example: id=1 → MM-dd-yyyy → '10-25-2000' | id=2 → dd-MM-yyyy → '25-10-2000' | id=3 → yyyy-MM-dd → '2000-10-25' | id=4 → dd-MMM-yyyy → '25-Oct-2000' 17. STEP 4: For EVERY DATETIMEPICKER field in the payload: parse any user-provided date and re-format it using the active unique_value pattern before sending. 18. NEVER assume a date format — always derive it from dateTimeFormatID. Wrong format = silent data loss. 19. === END DATE FORMAT CHECK === 20. 21. If user provides entityKey (e.g., MAC-TS-7), first call Fetch Test Suites with a filter on entityKeyId to resolve the id (test suite numeric id) and TsFolderID from rootFolders.TS.id. 22. To get valid values for owner, state, etc., call the 'Admin/Get info Service' API (FETCH_PROJECT_INFO tool) and use the returned customListObjs IDs. 23. CRITICAL: For testsuiteOwner mapping - Call API 'Admin/Get info Service', from the response get value from customListObjs.owner[].id. Match the user by customListObjs.owner[].name. 24. If the user provides an owner name, fetch project info, find the matching user in customListObjs.owner[index].name, and use its ID in the payload as testsuiteOwner. If the name is not found, skip the testsuiteOwner field (it is not required) and show a user-friendly message: 'Test suite updated without owner, as given owner is not available in the current project.' 25. CRITICAL: For testSuiteState mapping - Call API 'Admin/Get info Service', from the response get value from customListObjs.testSuiteState[].id. Match the state by customListObjs.testSuiteState[].name. 26. If the user provides a test suite state name, fetch project info, find the matching state in customListObjs.testSuiteState[index].name, and use its ID in the payload as testSuiteState. If the name is not found, skip the testSuiteState field (it is not required) and show a user-friendly message: 'Test suite updated without test suite state, as given state is not available in the current project.' 27. If either owner or state is not found in project info, the update for that field will be skipped and a user-friendly message will be shown to the user. 28. UDF fields in steps must match your QMetry custom field configuration. 29. All IDs (testSuiteState from customListObjs.testSuiteState[index].id, testsuiteOwner from customListObjs.owner[index].id) must be valid for your QMetry instance. 30. If a custom field is mandatory, include it in the UDF object. 31. 32. UDF (User Defined Fields) WORKFLOW FOR UPDATE: 33. 1. Call 'Fetch UDF Layout' with entityType='TS', pageName='DETAIL' to get field names, fieldIDs (projectUserFieldID), and list option IDs. 34. IF listOptions[field.listName] is empty after Fetch UDF Layout, the tool already tried a metadata fallback. If STILL empty, ask the user to provide the option ID from the QMetry UI — do NOT guess numeric IDs. 35. 2. For LOOKUPLIST fields: pick one ID from listOptions[field.listName][].id. 36. 3. For MULTILOOKUPLIST fields: pick array of IDs; also pass alias flat key (e.g., fieldNameAlias: 'Option Label'). 37. 4. For CASCADINGLIST fields: pick parent ID + fetch child with 'Fetch Cascade Child Values'. Pass { parent: parentId, child: childId }. 38. 5. Pass BOTH 'udfFields' (flat root values) AND 'UDF' wrapper (with fieldID) — both required for update. 39. Example: udfFields: { ts_field: 'value' }, UDF: { ts_field: { fieldID: 2001, value: 'value' } } 40. 6. Mandatory UDF fields (isMandatory=true) MUST be included.

Fetch QMetry test suites - automatically handles viewId resolution based on project

Toolset: Test Suites

Parameters:

• projectKey (string): Project key - unique identifier for the project (default: "default")

• viewId (number): ViewId for test suites - SYSTEM AUTOMATICALLY RESOLVES THIS. Leave empty unless you have a specific viewId. System will fetch project info using the projectKey and extract latestViews.TS.viewId automatically.

• folderPath (string): Folder path for test suites - SYSTEM AUTOMATICALLY SETS TO ROOT. Leave empty unless you want specific folder. System will automatically use empty string "" (root directory). Only specify if user wants specific folder like "Automation/Regression". (default: "")

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

• scope (string): Scope of the operation - defines the context for data retrieval. Common values: 'project' (default), 'folder', 'release', 'cycle'. Applies to any entity type being fetched or operated upon. (default: "project")

• getSubEntities (boolean): Whether to include sub-entities.

• filter (string): Filter criteria as JSON string (default '[]') (default: "[]")

• udfFilter (string): User-defined field filter as JSON string (default '[]') (default: "[]")

• sort (string): Sort Records - refer json schema, Possible property - entityKey, name, testsuiteStatus, linkedPlatformCount, linkedTcCount, createdDate, createdByAlias, updatedDate, updatedByAlias, attachmentCount, owner, remExecutionTime, totalExecutionTime (default: "[{"property":"name","direction":"ASC"}]")

Output Description: JSON object with 'data' array containing test suites and pagination info

Use Cases: 1. List all test suites in a project 2. Search for specific test suites using filters 3. Browse test suites in specific folders 4. Get paginated test suite results

Examples:

1. Get all test suites from default project - system will auto-fetch viewId

{}

Expected Output: List of test suites from default project with auto-resolved viewId

2. Get all test suites from UT project - system will auto-fetch UT project's viewId

{
  "projectKey": "UT"
}

Expected Output: List of test suites from UT project using UT's specific TS viewId

3. Get test suites by release/cycle filter

{
  "projectKey": "MAC",
  "filter": "[{\"value\":[55178],\"type\":\"list\",\"field\":\"release\"},{\"value\":[111577],\"type\":\"list\",\"field\":\"cycle\"}]"
}

Expected Output: Test suites associated with Release 8.12 (ID: 55178) and Cycle 8.12.1 (ID: 111577)

4. Get test suites by release only

{
  "projectKey": "MAC",
  "filter": "[{\"value\":[55178],\"type\":\"list\",\"field\":\"release\"}]"
}

Expected Output: All test suites associated with Release 8.12 (ID: 55178)

5. Get test suites by cycle only

{
  "projectKey": "MAC",
  "filter": "[{\"value\":[111577],\"type\":\"list\",\"field\":\"cycle\"}]"
}

Expected Output: All test suites associated with Cycle 8.12.1 (ID: 111577)

6. Search for specific test suite by entity key

{
  "projectKey": "MAC",
  "filter": "[{\"type\":\"string\",\"value\":\"MAC-TS-1684\",\"field\":\"entityKeyId\"}]"
}

Expected Output: Test suites matching the entity key criteria

7. Search for multiple test suites by comma-separated entity keys

{
  "projectKey": "MAC",
  "filter": "[{\"type\":\"string\",\"value\":\"MAC-TS-1684,MAC-TS-1685,MAC-TS-1686\",\"field\":\"entityKeyId\"}]"
}

Expected Output: Test suites matching any of the specified entity keys

Hints: 1. CRITICAL WORKFLOW: Always use the SAME projectKey for both project info and test suite fetching 2. Step 1: If user specifies projectKey (like 'UT', 'MAC'), use that EXACT projectKey for project info 3. Step 2: Get project info using that projectKey, extract latestViews.TS.viewId 4. Step 3: Use the SAME projectKey and the extracted TS viewId for fetching test suites 5. Step 4: If user doesn't specify projectKey, use 'default' for both project info and test suite fetching 6. NEVER mix project keys - if user says 'MAC project', use projectKey='MAC' for everything 7. For search by test suite key (like MAC-TS-1684), use filter: '[{"type":"string","value":"MAC-TS-1684","field":"entityKeyId"}]' 8. RELEASE/CYCLE FILTERING: Use release and cycle IDs, not names, for filtering 9. For release filter: '[{"value":[releaseId],"type":"list","field":"release"}]' 10. For cycle filter: '[{"value":[cycleId],"type":"list","field":"cycle"}]' 11. For combined release+cycle: '[{"value":[releaseId],"type":"list","field":"release"},{"value":[cycleId],"type":"list","field":"cycle"}]' 12. Get release/cycle IDs from FETCH_RELEASES_AND_CYCLES tool before filtering 13. FILTER FIELDS: name, release, cycle, platform, isArchived, testsuiteStatus, createdByAlias, createdDate, entityKeyId, attachmentCount, linkedPlatformCount, linkedTcCount, updatedByAlias, updatedDate, owner, remExecutionTime, and totalExecutionTime 14. SORT FIELDS: entityKey, name, testsuiteStatus, linkedPlatformCount, linkedTcCount, createdDate, createdByAlias, updatedDate, updatedByAlias, attachmentCount, remExecutionTime, and totalExecutionTime 15. For multiple entity keys, use comma-separated values in filter 16. Use empty string '' as folderPath for root directory

Get test suites that can be linked to test cases in QMetry with automatic viewId resolution

Toolset: Test Suites

Parameters:

• projectKey (string): Project key - unique identifier for the project (default: "default")

• tsFolderID (number): Test Suite folder ID. CRITICAL: the parameter name is 'tsFolderID' — do NOT use 'testSuiteFolderId', 'folderId', 'folderID', or other variants. Accepts a string or number. Get from project info response → rootFolders.TS.id. Use FETCH_PROJECT_INFO tool first if not provided by user.

• viewId (number): ViewId for test suite folders - SYSTEM AUTOMATICALLY RESOLVES THIS. Leave empty unless you have a specific viewId. System will fetch project info using the projectKey and extract latestViews.TSFS.viewId automatically.

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

• getColumns (boolean): Whether to get column information in response. (default: true)

• filter (string): Filter criteria as JSON string (default '[]') (default: "[]")

Output Description: JSON object with test suites array and pagination metadata

Use Cases: 1. Get test suites available for linking with test cases 2. Find appropriate test suites for test case organization 3. Browse test suites in specific folders for better management 4. Filter test suites by release, cycle, or archive status 5. Organize test execution by grouping test cases into test suites 6. Plan test suite structure for comprehensive test coverage 7. Manage test case categorization for reporting purposes 8. Search for existing test suites before creating new ones 9. Get root test suite folder contents using project info

Examples:

1. Get test suites from root folder using auto-resolved viewId

{
  "tsFolderID": 113557
}

Expected Output: List of test suites available in the root test suite folder with auto-resolved viewId

2. Get test suites with custom pagination and auto-resolved viewId

{
  "tsFolderID": 113557,
  "page": 1,
  "limit": 25
}

Expected Output: Paginated list of test suites with 20 items per page

3. Filter test suites by release with auto-resolved viewId

{
  "tsFolderID": 113557,
  "filter": "[{\"type\":\"list\",\"value\":[55178],\"field\":\"release\"}]"
}

Expected Output: Test suites associated with Release 8.12 (ID: 55178)

4. Filter test suites by cycle with auto-resolved viewId

{
  "tsFolderID": 113557,
  "filter": "[{\"type\":\"list\",\"value\":[111577],\"field\":\"cycle\"}]"
}

Expected Output: Test suites associated with Cycle 8.12.1 (ID: 111577)

5. Get only active (non-archived) test suites

{
  "tsFolderID": 113557,
  "filter": "[{\"value\":[0],\"type\":\"list\",\"field\":\"isArchived\"}]"
}

Expected Output: List of active test suites (not archived)

6. Filter test suites by release and cycle

{
  "tsFolderID": 113557,
  "filter": "[{\"type\":\"list\",\"value\":[55178],\"field\":\"release\"},{\"type\":\"list\",\"value\":[111577],\"field\":\"cycle\"}]"
}

Expected Output: Test suites associated with both Release 8.12 (ID: 55178) and Cycle 8.12.1 (ID: 111577)

7. Get test suites with column information

{
  "tsFolderID": 113557,
  "getColumns": true
}

Expected Output: Test suites list with detailed column metadata for better interpretation

8. Search test suites from specific sub-folder with manual viewId

{
  "tsFolderID": 42,
  "viewId": 104316
}

Expected Output: Test suites available in specific folder ID 42 for test case linking

Hints: 1. CRITICAL: tsFolderID is REQUIRED - Test Suite folder ID will be auto-resolved if not provided 2. viewId will be AUTOMATICALLY RESOLVED from project info if not provided 3. HOW TO GET tsFolderID: 4. 1. Call FETCH_PROJECT_INFO tool first to get project configuration 5. 2. From the response, use rootFolders.TS.id for the root test suite folder 6. 3. Example: rootFolders.TS.id = 113557 (MAC project root TS folder) 7. 4. If user doesn't specify tsFolderID, automatically use rootFolders.TS.id from project info 8. VIEWID AUTO-RESOLUTION: 9. 1. System automatically fetches project info using the projectKey 10. 2. Extracts latestViews.TSFS.viewId automatically 11. 3. Example: latestViews.TSFS.viewId = 104316 (MAC project TSFS view) 12. 4. Manual viewId only needed if you want to override the automatic resolution 13. WORKFLOW: System automatically handles project info if tsFolderID or viewId is not provided 14. PROJECT INFO STRUCTURE: rootFolders.TS.id contains the root test suite folder ID 15. PROJECT INFO STRUCTURE: latestViews.TSFS.viewId contains the test suite folder view ID 16. For sub-folders: Use specific folder IDs if you know them, or call folder listing APIs 17. FILTER CAPABILITIES: Same as other QMetry list operations 18. FILTER FIELDS: release, cycle, isArchived, name, status, priority 19. RELEASE/CYCLE FILTERING: Use numeric IDs in list format (get from FETCH_RELEASES_AND_CYCLES) 20. ARCHIVE FILTERING: 0=Active, 1=Archived 21. getColumns=true provides additional metadata for result interpretation 22. Multiple filter conditions are combined with AND logic 23. Pagination supported for large result sets (start, page, limit parameters) 24. This tool helps organize test cases into logical test suites 25. Essential for test execution planning and test case management 26. Use this before creating new test suites to check existing ones

Link test cases to a test suite in QMetry.

Toolset: Test Suites

Parameters:

• tsID (number) required: Id of Test Suite (required). CRITICAL: parameter name is 'tsID' — do NOT use 'testSuiteId', 'testSuiteID', or other variants.

• tcvdIDs (array) required: Array of Test Case Version IDs (required if fromReqs is false). CRITICAL: parameter name is 'tcvdIDs' — do NOT use 'tcVersionIds', 'testCaseVersionIds', or other variants.

• fromReqs (boolean): Link TestCases from Requirements (optional, default false)

Output Description: JSON object with linkage status and details.

Use Cases: 1. Link test cases to a test suite by entity keys 2. Bulk link multiple test cases to a suite 3. Automate test suite composition from test cases

Examples:

1. Link test cases to a test suite

{
  "tsID": 8674,
  "tcvdIDs": [
    5448504,
    5448503
  ],
  "fromReqs": false
}

Expected Output: Test cases QTM-TC-32 and QTM-TC-35 linked to test suite 8674.

2. Link test cases directly to test suites with test cases entityKeys VT-TC-9, VT-TC-10 to test suite id 1487397

{
  "tsID": 1487397,
  "tcvdIDs": [
    5448504,
    5448503
  ],
  "fromReqs": false
}

Expected Output: Test cases VT-TC-9 and VT-TC-10 linked to test suite 1487397.

3. Link test case VT-TC-4, VT-TC-1,VT-TC-101, VT-TC-22 to test suite VT-TS-3

{
  "tsID": 1487397,
  "tcvdIDs": [
    5448504,
    5448503,
    5448505,
    5448506
  ],
  "fromReqs": false
}

Expected Output: Test cases VT-TC-4, VT-TC-1, VT-TC-101, and VT-TC-22 linked to test suite VT-TS-3.

Hints: 1. To get the tsID, call the Fetch Test Suites for Test Case API with rootFolderId otherwise if given folderid so use that and from response get the id. 2. To get the tcvdIDs by testcase entityKey, call the Testcase/Fetch Versions API and use data[].tcVersionID. 3. Set fromReqs to false to direct test case linkage.

Link test cases (including those linked to requirements) to a test suite in QMetry.

Toolset: Test Suites

Parameters:

• tsID (number) required: Id of Test Suite (required). CRITICAL: parameter name is 'tsID' — do NOT use 'testSuiteId', 'testSuiteID', or other variants.

• tcvdIDs (array) required: Array of Test Case Version IDs (required if fromReqs is true). CRITICAL: parameter name is 'tcvdIDs' — do NOT use 'tcVersionIds', 'testCaseVersionIds', or other variants.

• fromReqs (boolean): Link TestCases from Requirements (optional, default true)

Output Description: JSON object with linkage status and details.

Use Cases: 1. Link requirements linked test cases to a test suite 2. Bulk link multiple requirements linked test cases to a suite 3. Automate test suite composition from requirements linked test cases

Examples:

1. VT-RQ-18 Requirements Linked test cases to a test suite

{
  "tsID": 8674,
  "tcvdIDs": [
    5448504,
    5448503
  ],
  "fromReqs": true
}

Expected Output: Test cases QTM-TC-32 and QTM-TC-35 linked to test suite 8674.

2. VT-RQ-19 Requirements Linked test cases to test suites id 1487397

{
  "tsID": 1487397,
  "tcvdIDs": [
    5448504,
    5448503
  ],
  "fromReqs": true
}

Expected Output: Test cases VT-TC-9 and VT-TC-10 linked to test suite 1487397.

3. VT-RQ-20 Requirements Linked test case to test suite VT-TS-3

{
  "tsID": 1487397,
  "tcvdIDs": [
    5448504,
    5448503,
    5448505,
    5448506
  ],
  "fromReqs": true
}

Expected Output: Test cases VT-TC-4, VT-TC-1, VT-TC-101, and VT-TC-22 linked to test suite VT-TS-3.

Hints: 1. To get the tsID, call the Fetch Test Suites for Test Case API with rootFolderId otherwise if given folderid so use that and from response get the id. 2. To get the requirement linked tcvdIDs by requirement entityKey, call the Fetch Test Cases Linked to Requirement API by to fetch If user provides entityKey (e.g., MAC-RQ-1011), first call FETCH_REQUIREMENTS with filter on entityKeyId to resolve the numeric rqID and get the linked test cases version ids. 3. Set fromReqs to true to link requirements linked test cases instead of direct test case linkage.

Link one or more platforms to a QMetry Test Suite.

Toolset: Test Suites

Parameters:

• projectKey (string): Project key - unique identifier for the project (default: "default")

• qmTsId (number) required: Id of Test Suite (required). CRITICAL: the parameter name is 'qmTsId' — do NOT use 'tsId', 'testSuiteId', 'tsID', or other variants. Accepts a string or number. To get the qmTsId - Call API 'Testsuite/Fetch Testsuite'. From the response, get value -> data[].id

• qmPlatformId (string) required: Comma-separated Platform IDs (required). CRITICAL: the parameter name is 'qmPlatformId' — do NOT use 'platformId', 'platformID', 'platformIds', or other variants. Accepts a number or string. To get the qmPlatformId - Call API 'Platform/List'. From the response, get value -> data[].platformID

Output Description: JSON object with linkage status, success message, and details.

Use Cases: 1. Link a single platform to a test suite 2. Link multiple platforms to a test suite for cross-platform testing 3. Define execution environments for a test suite 4. Organize test suites by supported platforms 5. Set up platform-specific test suite configurations

Examples:

1. Link single platform to a test suite

{
  "qmTsId": 1511970,
  "qmPlatformId": "63004"
}

Expected Output: Platform 63004 linked to test suite 1511970 successfully.

2. Link multiple platforms to a test suite

{
  "qmTsId": 1511970,
  "qmPlatformId": "63004,63005,63006"
}

Expected Output: Platforms 63004, 63005, 63006 linked to test suite 1511970 successfully.

Hints: 1. CRITICAL: qmTsId and qmPlatformId are REQUIRED parameters 2. To get the qmTsId (Test Suite ID): 3. 1. Call 'Testsuite/Fetch Testsuite' API 4. 2. From response, use data[].id 5. 3. Example: Test Suite 'Login Tests' might have ID 1511970 6. To get the qmPlatformId (Platform ID): 7. 1. Call 'Platform/List' API (Fetch Platforms tool) 8. 2. From response, use data[].platformID 9. 3. Example: Platform 'Chrome' might have ID 63004 10. qmPlatformId accepts comma-separated values for multiple platforms 11. Format for multiple platforms: '63004,63005,63006' 12. No spaces in the comma-separated list 13. If test suite entity key (e.g., VT-TS-12) is provided, first fetch test suites to resolve numeric ID 14. Platforms represent browsers, operating systems, devices, or custom environments 15. This tool helps organize cross-platform test execution 16. Essential for comprehensive platform coverage testing

Get test cases that are linked (or not linked) to a specific test suite in QMetry

Toolset: Test Suites

Parameters:

• projectKey (string): Project key - unique identifier for the project (default: "default")

• tsID (number) required: Test Suite numeric ID. CRITICAL: the parameter name is 'tsID' — do NOT use 'testSuiteId', 'testSuiteID', 'suiteId', or other variants. Accepts a string or number. NOTE: To get the tsID - Call API 'Testsuite/Fetch Testsuite' From the response, get value of following attribute -> data[].id

• getLinked (boolean): True to get only those issues that are linked with this Test case Run, False to get those issues which are not linked with this Test case Run. Default value true (get linked issues). (default: true)

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

• filter (string): Filter criteria as JSON string (default '[]') (default: "[]")

Output Description: JSON object with test cases array containing test case details, properties, and suite linkage information

Use Cases: 1. Get all test cases linked to a specific test suite for execution planning 2. Find test cases that are NOT linked to a test suite (gap analysis) 3. Analyze test suite composition and coverage 4. Filter linked test cases by various criteria 5. Plan test execution based on test suite structure 6. Generate test suite reports and documentation 7. Validate test suite contents before execution 8. Manage test case organization within test suites 9. Export test suite details for external reporting 10. Verify test case assignments in test suites

Examples:

1. Get all test cases linked to test suite ID 1497291 (default behavior)

{
  "tsID": 1497291
}

Expected Output: List of test cases linked to the test suite with test case details and metadata

2. Get all test cases linked to test suite ID 1497291 (explicit)

{
  "tsID": 1497291,
  "getLinked": true
}

Expected Output: List of test cases linked to the test suite with test case details and metadata

3. Get test cases NOT linked to test suite (gap analysis)

{
  "tsID": 1497291,
  "getLinked": false
}

Expected Output: List of test cases that are NOT linked to the test suite

4. Get linked test cases with custom pagination

{
  "tsID": 1497291,
  "getLinked": true,
  "page": 1,
  "limit": 25
}

Expected Output: Paginated list of linked test cases with 50 items per page

5. Filter linked test cases by priority (using default getLinked=true)

{
  "tsID": 1497291,
  "filter": "[{\"value\":[1,2],\"type\":\"list\",\"field\":\"priorityAlias\"}]"
}

Expected Output: High and medium priority test cases linked to the suite

6. Filter linked test cases by status

{
  "tsID": 1497291,
  "getLinked": true,
  "filter": "[{\"value\":[1],\"type\":\"list\",\"field\":\"testCaseStateAlias\"}]"
}

Expected Output: Active test cases linked to the test suite

Hints: 1. CRITICAL: tsID parameter is REQUIRED - this is the Test Suite numeric ID 2. getLinked parameter is OPTIONAL - defaults to true if not provided 3. HOW TO GET tsID: 4. 1. Call API 'Testsuite/Fetch Testsuite' to get available test suites 5. 2. From the response, get value of following attribute -> data[].id 6. 3. Example: Test Suite 'Regression Suite' might have ID 1497291 7. tsID is NOT the same as tsFolderID - tsID refers to a specific test suite, not a folder 8. getLinked=true (default): Returns test cases that ARE linked to the test suite 9. getLinked=false: Returns test cases that are NOT linked to the test suite (useful for gap analysis) 10. If getLinked is not specified, it defaults to true (linked test cases) 11. FILTER CAPABILITIES: Support filtering by test case properties 12. FILTER FIELDS: priorityAlias (list), testCaseStateAlias (list), testingTypeAlias (list), testCaseTypeAlias (list), componentAlias (list), owner (list) 13. PRIORITY IDs: Typically 1=High, 2=Medium, 3=Low (verify with your QMetry instance) 14. STATUS IDs: Typically 1=Active, 2=Review, 3=Deprecated (verify with your QMetry instance) 15. TESTING TYPE IDs: Typically 1=Manual, 2=Automated (verify with your QMetry instance) 16. TYPE IDs: Typically 1=Functional, 2=Integration, 3=System (verify with your QMetry instance) 17. Multiple filter conditions are combined with AND logic 18. Use pagination for large result sets (start, page, limit parameters) 19. This tool is essential for test suite management and execution planning 20. Helps verify test suite composition before test runs 21. Critical for understanding test coverage within specific suites 22. Use for test suite analysis and optimization

Get executions for a given test suite in QMetry

Toolset: Test Suites

Parameters:

• projectKey (string): Project key - unique identifier for the project (default: "default")

• tsID (number) required: Test Suite numeric ID. CRITICAL: the parameter name is 'tsID' — do NOT use 'testSuiteId', 'testSuiteID', 'suiteId', or other variants. Accepts a string or number. NOTE: To get the tsID - Call API 'Testsuite/Fetch Testsuite' From the response, get value of following attribute -> data[].id

• tsFolderID (number): Test Suite folder ID. CRITICAL: the parameter name is 'tsFolderID' — do NOT use 'testSuiteFolderId', 'folderId', 'folderID', or other variants. Accepts a string or number. Get from project info response → rootFolders.TS.id. Use FETCH_PROJECT_INFO tool first if not provided by user.

• gridName (string): Grid Name to be displayed (default 'TESTEXECUTIONLIST')

• viewId (number): ViewId for test execution - SYSTEM AUTOMATICALLY RESOLVES THIS. Leave empty unless you have a specific viewId. System will fetch project info using the projectKey and extract latestViews.TE.viewId automatically.

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

• filter (string): Filter criteria as JSON string (default '[]') (default: "[]")

Output Description: JSON object with executions array containing execution details, status, platforms, releases, and execution metadata

Use Cases: 1. Get all executions for a specific test suite for reporting purposes 2. Analyze test execution results and trends within a test suite 3. Filter executions by release, cycle, platform, or automation status 4. Monitor test suite execution performance across different environments 5. Generate execution reports for specific test suites 6. Track execution history and patterns for test suite optimization 7. Validate test suite execution coverage across releases and cycles 8. Audit test execution data for compliance and quality assurance 9. Export execution data for external reporting and analytics

Examples:

1. Get all executions for test suite ID 194955

{
  "tsID": 194955
}

Expected Output: List of executions for the test suite with execution details, status, and metadata

2. Get executions with test suite folder and view ID

{
  "tsID": 194955,
  "tsFolderID": 126554,
  "viewId": 41799
}

Expected Output: Executions filtered by test suite folder and specific view configuration

3. Filter executions by release and cycle

{
  "tsID": 194955,
  "filter": "[{\"type\":\"list\",\"value\":[55178],\"field\":\"releaseID\"},{\"type\":\"list\",\"value\":[111577],\"field\":\"cycleID\"}]"
}

Expected Output: Executions filtered by specific release (55178) and cycle (111577)

4. Filter executions by platform and automation status

{
  "tsID": 194955,
  "filter": "[{\"type\":\"list\",\"value\":[12345],\"field\":\"platformID\"},{\"type\":\"boolean\",\"value\":true,\"field\":\"isAutomatedFlag\"}]"
}

Expected Output: Automated executions filtered by specific platform (12345)

5. Get only active (non-archived) executions

{
  "tsID": 194955,
  "filter": "[{\"value\":[0],\"type\":\"list\",\"field\":\"isArchived\"}]"
}

Expected Output: Active executions that are not archived

6. Get executions with custom pagination and grid name

{
  "tsID": 194955,
  "gridName": "TESTEXECUTIONLIST",
  "page": 1,
  "limit": 25
}

Expected Output: Paginated list of executions with 25 items per page using specific grid configuration

Hints: 1. !MOST IMPORTANT HOW TO GET viewId: 2. CRITICAL: Always resolve and use the correct test execution viewId for the current project when calling this tool. 3. The viewId parameter must be fetched from the active project's info (latestViews.TEL.viewId). 4. Each QMetry project may have a different test execution list viewId, so using a stale or incorrect viewId will result in incomplete or invalid executions list data by test suite id. 5. Usage workflow: 6. 1. Fetch project info for the current project (Admin/Get info Service). 7. 2. Extract latestViews.TEL.viewId from the response. 8. 3. Use this viewId in the Fetch Test Case Runs by Test Suite Run API call. 9. Example: 10. { 11. tsID: 1533730, 12. viewId: 94194, 13. gridName: 'TESTEXECUTIONLIST' 14. } 15. CRITICAL: tsID parameter is REQUIRED - this is the Test Suite numeric ID 16. HOW TO GET tsID: 17. 1. Call API 'Testsuite/Fetch Testsuite' to get available test suites 18. 2. From the response, get value of following attribute -> data[].id 19. 3. Example: Test Suite 'Regression Suite' might have ID 194955 20. HOW TO GET tsFolderID (optional): 21. 1. Call API 'Testsuite/List of folders' to get test suite folders 22. 2. From the response, get value of following attribute -> data[].id 23. 3. Example: Test Suite folder might have ID 126554 24. FILTER CAPABILITIES: Extensive filtering by execution properties 25. FILTER FIELDS: releaseID (list), cycleID (list), platformID (list), isAutomatedFlag (boolean), isArchived (list) 26. RELEASE/CYCLE FILTERING: Use numeric IDs in list format (get from FETCH_RELEASES_AND_CYCLES) 27. PLATFORM FILTERING: Use numeric platform IDs (get from FETCH_PLATFORMS) 28. AUTOMATION STATUS: Use boolean true/false for isAutomatedFlag field 29. ARCHIVE STATUS: 0=Active executions, 1=Archived executions 30. GRID NAME: Default is 'TESTEXECUTIONLIST' - used for execution list display configuration 31. VIEW ID: Optional numeric identifier for specific execution view configurations 32. Multiple filter conditions are combined with AND logic 33. Use pagination for large execution result sets (start, page, limit parameters) 34. This tool is essential for test execution analysis and reporting 35. Critical for monitoring test suite performance and execution trends 36. Use for compliance reporting and execution audit trails 37. Essential for test execution planning and resource optimization

Get test case runs under a specific test suite run execution in QMetry, including Test Run UDF values. ALWAYS present results as a unified table: Test Case Key | Test Case Summary | Executed Version | Execution Status | <UDF Label columns…>. NEVER show a separate type+value breakdown — always combine identification fields and UDF values in one table per run.

Toolset: Test Suites

Parameters:

• projectKey (string): Project key - unique identifier for the project (default: "default")

• tsrunID (string) required: Test Suite Run ID. CRITICAL: the parameter name is 'tsrunID' — do NOT use 'testSuiteRunId', 'tsRunID', 'testSuiteRunID', or any other variant. Accepts a string or number (e.g. 731600 or '731600' — both are valid). To get this value: Call 'Fetch Executions by Test Suite' → use data[].tsRunID from the response.

• viewId (number): ViewId for test execution - SYSTEM AUTOMATICALLY RESOLVES THIS. Leave empty unless you have a specific viewId. System will fetch project info using the projectKey and extract latestViews.TE.viewId automatically.

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

• filter (string): Filter criteria as JSON string (default '[]') (default: "[]")

• udfFilter (string): User-defined field filter as JSON string (default '[]') (default: "[]")

• tcrUdfFilter (string): Test Case Run (TCR) UDF filter as JSON string (default '[]'). Used to filter test case runs by Test Run UDF field values. Format: '[{"type":"list","value":[,],"field":""}]'. Example: '[{"type":"list","value":[5108701,5108697],"field":"8260LUP"}]' filters runs where the UDF field '8260LUP' has those list item IDs. (default: "[]")

• showTcWithDefects (boolean): Show test case runs with linked defects (default: false)

Output Description: JSON object with test case runs array. Each row ALWAYS contains these mandatory identification fields: 'entityKey' (Test Case Key, e.g. 'MAC-TC-123'), 'summary' (Test Case Summary/name), 'latestVersion' (Executed Version, e.g. 'v1', 'v2'), 'runStatus' (Execution Status label, e.g. 'Passed', 'Failed', 'Not Run'), 'runStatusID' (numeric status ID), 'tcRunID' (numeric Test Run ID), and 'testRunUdfs' (object with Test Run UDF field keys mapped to their values, parsed from the raw 'udfjson' field; HTML stripped from rich text). UDF values can also be fetched in enriched form via FETCH_TEST_RUN_UDF_VALUES or field metadata via FETCH_TEST_RUN_UDF_METADATA. The top-level response includes 'hasTcRunUdf' (boolean), 'total' (count), and pagination metadata.

Use Cases: 1. Get all test case runs under a specific test suite run execution 2. Fetch Test Run UDF values for all test case executions in a test suite run — always show Test Case Key, Summary, and Execution Status alongside UDFs 3. Fetch Test Run UDF values for a specific test case execution by tcRunID 4. Filter test case runs by Test Run UDF field values (e.g. show only runs where dropdown UDF = specific option) 5. Analyze individual test case execution results, status, and custom UDF metadata 6. Monitor test case run performance and execution trends 7. Generate detailed test execution reports including custom UDF data 8. Track test case run history and execution patterns 9. Validate test case run coverage and execution completeness 10. Audit test case run data with UDF values for compliance and quality assurance 11. Export detailed test case run data including Test Run UDFs for external reporting 12. Retrieve paginated test case run results for large test suite executions

Examples:

1. Get all test case runs for test suite run ID '107021'

{
  "tsrunID": "107021",
  "viewId": 6887
}

Expected Output: Present as ONE unified table — never as a separate type+value breakdown. Example: | Test Case Key | Test Case Summary | Executed Version | Execution Status | Tested By | Environments UDF | Execution Type | Country | | MAC-TC-5 | Login - valid credential | v1 | Passed | varis | chrome, edge, safari | Functional | India > i3 | | MAC-TC-6 | Login - invalid password | v2 | Failed | john | firefox | Regression | - | Columns: Test Case Key (entityKey) | Test Case Summary (summary) | Executed Version (latestVersion) | Execution Status (runStatus) | then one column per UDF label. Use the UDF 'label' as column header. Show null UDF values as '-'.

2. Fetch Test Run UDF values for all executions in test suite run '728995'

{
  "tsrunID": "728995",
  "viewId": 79451,
  "start": 0,
  "page": 1,
  "limit": 20
}

Expected Output: Present as ONE unified table combining identification fields and UDF values — never a separate type+value breakdown. Example: | Test Case Key | Test Case Summary | Executed Version | Execution Status | Tested By | Environments UDF | Planned Execution Date | Execution Type | | MAC-TC-5 | Login test | v1 | Passed | varis | chrome, edge, safari | - | Functional | HTML is stripped from LARGETEXT UDF fields. Null values shown as '-'.

3. Filter by Test Run UDF list/dropdown field (single-select or multi-select lookup) — runs where UDF '8260LUP' has list item IDs 5108701 or 5108697

{
  "tsrunID": "728995",
  "viewId": 79451,
  "tcrUdfFilter": "[{\"type\":\"list\",\"value\":[5108701,5108697],\"field\":\"8260LUP\"}]"
}

Expected Output: Filtered test case runs matching the lookup list UDF values

4. Filter by Test Run UDF multi-lookup list field — runs where multi-select UDF 'PGTE_MULTILOOKUPLIST' contains list item IDs 5126503 or 5126502

{
  "tsrunID": "728995",
  "viewId": 79451,
  "tcrUdfFilter": "[{\"type\":\"list\",\"value\":[5126503,5126502],\"field\":\"PGTE_MULTILOOKUPLIST\"}]"
}

Expected Output: Filtered test case runs where multi-lookup UDF matches any of the given list item IDs

5. Filter by Test Run UDF cascading dropdown field — runs where cascading UDF 'cascade_vK' has list item IDs 5126498 or 5126499 (must set isCascading:true)

{
  "tsrunID": "728995",
  "viewId": 79451,
  "tcrUdfFilter": "[{\"type\":\"list\",\"value\":[5126498,5126499],\"field\":\"cascade_vK\",\"isCascading\":true}]"
}

Expected Output: Filtered test case runs matching the cascading dropdown UDF values

6. Filter by Test Run UDF short text field — runs where text UDF 'TRString' contains the value 'str'

{
  "tsrunID": "728995",
  "viewId": 79451,
  "tcrUdfFilter": "[{\"type\":\"string\",\"field\":\"TRString\",\"value\":\"str\"}]"
}

Expected Output: Filtered test case runs where short text UDF matches the search string

7. Filter by Test Run UDF large text field — runs where large text UDF 'vk_large_text' contains 'this is large text'

{
  "tsrunID": "728995",
  "viewId": 79451,
  "tcrUdfFilter": "[{\"type\":\"string\",\"field\":\"vk_large_text\",\"value\":\"this is large text\"}]"
}