invarium_list_scenarios
List test scenarios for an agent. Shows each scenario’s title, ID, status, complexity, and test case count.
When to Use
Call invarium_list_scenarios to browse the scenarios registered for an agent. Common use cases:
- Reviewing which scenarios exist before generating new ones
- Filtering by status to find failing or flaky scenarios that need attention
- Paginating through a large scenario set
See Test Scenarios for background on how scenarios are structured.
Parameters
invarium_list_scenariosList test scenarios for an agent. Shows each scenario's title, ID, status, complexity, and test case count. Supports filtering by status and active state with pagination.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
agent_name | string | required | Name of the agent whose scenarios to list. |
status | string | null | default: null | Filter by status: passed, failed, flaky, or not_run. Omit to show all statuses. |
active | boolean | null | default: null | Filter by active state. true returns only active scenarios, false returns only inactive. Omit to show all. |
page | int | default: 1 | Page number for pagination. Must be >= 1. |
limit | int | default: 20 | Number of scenarios per page. Must be >= 1. |
Returns
Formatted list of scenarios with status, title, ID, complexity, and test case count. Includes pagination info.
Example
Scenarios for 'customer-support-agent' (12 total, page 1/1):
1. [PASSED] Happy path - product search
ID: sc_abc123 | Complexity: simple | Test cases: 5
2. [FAILED] Edge case - empty cart checkout
ID: sc_def456 | Complexity: edge_case | Test cases: 3
3. [NOT_RUN] Guardrail test - PII handling
ID: sc_ghi789 | Complexity: complex | Test cases: 4Response
The tool returns a formatted text list with pagination information:
Scenarios for 'customer-support-agent' (12 total, page 1/1):
1. [PASSED] Happy path - product search
ID: sc_abc123 | Complexity: simple | Test cases: 5
2. [FAILED] Edge case - empty cart checkout
ID: sc_def456 | Complexity: edge_case | Test cases: 3
3. [NOT_RUN] Guardrail test - PII handling
ID: sc_ghi789 | Complexity: complex | Test cases: 4Response Fields
Each scenario entry includes:
| Field | Description |
|---|---|
| Status | Current test status: PASSED, FAILED, FLAKY, or NOT_RUN. Shown in brackets. |
| Title | The scenario name or title. |
| ID | Unique scenario identifier. Use this with invarium_manage_scenario. |
| Complexity | Scenario difficulty level: simple, moderate, complex, mixed, or edge_case. |
| Test cases | Number of test cases within the scenario. |
Status Values
| Status | Meaning |
|---|---|
| PASSED | All test cases in the scenario passed on the last run. |
| FAILED | One or more test cases failed on the last run. |
| FLAKY | The scenario has inconsistent results across recent runs. |
| NOT_RUN | The scenario has not been executed yet. |
Examples
List All Scenarios
"List all scenarios for my customer-support-agent."Filter by Failing Status
Show only scenarios that failed on their last run:
"Show me the failing scenarios for my customer-support-agent."Paginate Through Results
For agents with many scenarios, use page and limit to paginate:
"List scenarios for my customer-support-agent, page 2, 10 per page."Error Responses
| Error | Cause | Fix |
|---|---|---|
Authentication failed | Invalid or missing API key. | Verify your INVARIUM_API_KEY is set correctly. Run invarium_connect first. |
Agent 'xyz' not found | No agent with this name exists in your workspace. | Check the agent name spelling. Use invarium_list_agents to see available agents. |
Invalid status 'xyz' | The status parameter is not a recognized value. | Use one of: passed, failed, flaky, not_run. |
Invalid page: must be a positive integer | The page parameter is less than 1 or not an integer. | Use a positive integer for page. |
Invalid limit: must be a positive integer | The limit parameter is less than 1 or not an integer. | Use a positive integer for limit. |
No scenarios found for 'xyz' | The agent has no scenarios matching the filters. | Generate scenarios first with invarium_generate_tests, or broaden your filters. |
See Error Codes for the full error reference.