Loadster MCP Tool Reference
This page lists every tool the Loadster MCP server offers your AI assistant. The reference below is
generated from the same tool definitions the server sends an assistant when it connects, so the names, descriptions,
hints, and parameters here match what your assistant sees. Each tool has its own anchor, so you can link straight to
one, like play_script.
Read, Write, and Sensitive Write MCP Tools
Every tool carries the four standard MCP behavior hints (readOnlyHint, destructiveHint, idempotentHint, and
openWorldHint), and Loadster sorts each tool into one of three classes based on them:
- Read tools only look things up, like listing scripts or reading a test report. They don’t change anything.
- Write tools create or change things in your Loadster account in ways you can undo, like creating a script or saving a new script revision.
- Sensitive write tools delete something, replace something that has no revision history to restore, or reach outside Loadster. Playing a script is in this class because it sends real traffic to the site the script tests.
The class is published with each tool (as com.loadster/toolClass in its _meta), so assistants that treat sensitive
writes differently can ask for your approval on those. Whether you actually see an approval prompt depends on your
assistant and its settings.
What Loadster MCP Tools Can’t Do
Some things are left to humans in the Loadster dashboard. No MCP tool launches or stops a full load test, enables a monitor, or spends Fuel, and none of them manage notification policies, maintenance windows, your team, or billing. An assistant can save a load test scenario, but you launch it yourself. Monitors are created disabled, and the only change an assistant can make to a monitor’s state is disabling it.
Playing a script runs a single bot, which is how an assistant checks that a script works before you use it in a load test. As with any script, point it only at sites you own or are authorized to test.
MCP Rate Limits and Usage Limits
These are the limits that apply to MCP tool calls today:
- Script plays: each person and each team can only have a limited number of scripts playing at once. When that
limit is reached,
play_scriptreturns an error until a play finishes or is stopped withstop_script. A single play also stops when it reaches its maximum duration. - Account limits: the same limits apply to an assistant as to you in the dashboard, like the maximum number of projects.
- Argument sizes: some arguments have a maximum length, which is listed in the parameter tables below and in the tool definitions an assistant reads. A longer value is rejected rather than cut short.
Beyond these, there’s no separate per-call quota on MCP tool calls. MCP calls also don’t count against the REST API’s per-endpoint rate limits, because they don’t go through those endpoints.
How MCP Tool Errors Are Reported
When a tool can’t do what was asked, it answers with a tool error (isError: true) and a short message meant to be
read, like Project not found, rather than failing the whole request. A wrong or missing argument gets a message that
names the argument and what it expected, so the assistant can correct itself and try again. If something unexpected
goes wrong inside Loadster, the message only says which tool failed and suggests trying again, and the details stay in
our logs.
- Project, Script, and Play Tools:
create_project,create_script,delete_script,delete_script_asset,duplicate_script,get_play_status,get_screenshot,get_script,get_script_asset,get_script_revision,get_step_detail,import_script,list_projects,list_script_assets,list_script_revisions,list_scripts,play_script,put_script_asset,restore_script_revision,stop_script,update_script - Script Authoring Tools:
get_command_schema,get_example,get_scripting_api,get_variable_schema,list_command_types,validate_script - Dataset Tools:
append_dataset_rows,create_dataset,delete_dataset,get_dataset,list_datasets,update_dataset - Load Test Scenario Tools:
create_scenario,delete_scenario,get_scenario,list_scenarios,update_scenario - Engine Tools:
list_engines - Load Test Report Tools:
get_load_test_report,list_load_tests,update_load_test_notes - Monitoring and Incident Tools:
create_monitor,delete_monitor,disable_monitor,get_incident,get_monitor,get_monitor_cycle_detail,get_monitoring_summary,list_incidents,list_monitor_cycles,list_monitoring_locations,list_monitors,update_monitor - Manual Tools:
get_documentation - Feedback Tool:
submit_feedback
Project, Script, and Play Tools
create_project
Create Project · Write · readOnlyHint: false · destructiveHint: false · idempotentHint: false · openWorldHint: false
Create a project for the connected team and return its id, name, and dashboard link. Prefer an existing project: call list_projects first, and create a new one only if the team has none or the user explicitly asked for one. When unsure, ask the user before creating.
| Parameter | Type | Required | Description |
|---|---|---|---|
name |
string | yes | The name of the new project. |
create_script
Create Script · Write · readOnlyHint: false · destructiveHint: false · idempotentHint: false · openWorldHint: false
Create a new script in a project. Read the relevant get_documentation topics and use the schema tools first to build valid commands for the bot type. HTTP is a Protocol Bot script, BROWSER is a Browser Bot script, and PLAYWRIGHT is a Playwright script. “Browser script” is ambiguous: Browser Bot and Playwright are different types, so if the user’s wording doesn’t say which, ask before creating. Don’t create multiple scripts of the same type for one task. Edit and reuse a script you created earlier in the session (same type, created by you, not used in a scenario or monitor elsewhere) instead of making a new one for a probe or a retry. Like every write on this surface, returns a summary — the server-assigned facts and a dashboard link — never the object you sent; the matching get tool reads it back.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId |
string | yes | |
script |
object | yes | The script name, type (HTTP, BROWSER, or PLAYWRIGHT), commands, and variables. HTTP is a Protocol Bot script, BROWSER is a Browser Bot script, and PLAYWRIGHT is a Playwright script. “Browser script” is ambiguous: Browser Bot and Playwright are different types, so if the user’s wording doesn’t say which, ask before creating. Don’t create multiple scripts of the same type for one task. Edit and reuse a script you created earlier in the session (same type, created by you, not used in a scenario or monitor elsewhere) instead of making a new one for a probe or a retry. |
delete_script
Delete Script · Sensitive write · readOnlyHint: false · destructiveHint: true · idempotentHint: false · openWorldHint: false
Delete a script from a project.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId |
string | yes | |
scriptId |
string | yes |
delete_script_asset
Delete Script Asset · Sensitive write · readOnlyHint: false · destructiveHint: true · idempotentHint: false · openWorldHint: false
Delete a file attached to a script.
| Parameter | Type | Required | Description |
|---|---|---|---|
path |
string | yes | The asset path. |
projectId |
string | yes | |
scriptId |
string | yes |
duplicate_script
Duplicate Script · Write · readOnlyHint: false · destructiveHint: false · idempotentHint: false · openWorldHint: false
Duplicate a script, optionally with a new name and into another project the token can access. Returns the copy’s summary.
| Parameter | Type | Required | Description |
|---|---|---|---|
destinationProjectId |
string | no | Optional destination project id; defaults to the source project. |
name |
string | no | Optional name for the copy; a name is generated when omitted. |
projectId |
string | yes | The project id of the source script. |
scriptId |
string | yes | The id of the script to duplicate. |
get_play_status
Get Play Status · Read · readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false
Get the current state of a play, with per-step results and log that fill in as it progresses, optionally waiting for it to finish. After play_script, call this with waitSeconds instead of sleeping between polls; the results are complete once running is false. Each step’s has-flags (hasBody, hasLog, and their siblings) say which get_step_detail parts would return something for that step, so drill down only where a flag is true. On a Playwright run the whole runner log belongs to the command step that ran the spec file — hasLog points there. A step’s screenshotKeys are in capture order; a Playwright step lists the script’s own page.screenshot calls in order, with the runner’s final screenshot of the test last.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId |
string | yes | |
scriptRunId |
string | yes | The script run id returned by play_script. |
waitSeconds |
integer | no | Optional: wait up to this many seconds (capped at 30) and return the moment the play reaches a terminal state. On expiry it returns the current status rather than an error, so just call again for a longer run. Omit for an immediate read. |
get_screenshot
Get Screenshot · Read · readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false
Fetch a screenshot captured during a play as a viewable image. Use the screenshotKey from a step in get_play_status.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId |
string | yes | |
screenshotKey |
string | yes | The screenshotKey reported by a step in get_play_status. |
scriptRunId |
string | yes |
get_script
Get Script · Read · readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false
Get a single script including its full command list and variables, plus a dashboard link. The variables are the script’s dataset bindings — the ${…} references in its commands resolve through them.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId |
string | yes | |
scriptId |
string | yes |
get_script_asset
Get Script Asset · Read · readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false
Read a script asset’s content as base64.
| Parameter | Type | Required | Description |
|---|---|---|---|
path |
string | yes | The asset path. |
projectId |
string | yes | |
scriptId |
string | yes |
get_script_revision
Get Script Revision · Read · readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false
Get a specific past revision of a script, including its commands, so you can inspect or diff it.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId |
string | yes | |
scriptId |
string | yes | |
version |
integer | yes | The revision version number. |
get_step_detail
Get Step Detail · Read · readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false
Read the payloads get_play_status leaves out — response bodies, headers, captured values, console messages, network activity, page HTML, logs — for one or more steps of a play, choosing the parts per call. Ask for several steps at once: a failing request and the earlier step that captured the token it used is one call. Use this instead of adding a validator or code block to the script just to echo a response back to yourself. Parts are bot-type-shaped, and asking for a part a run has no source for returns an error naming what it does have.
| Parameter | Type | Required | Description |
|---|---|---|---|
parts |
array of string | yes | The parts to return: body, headers, captured, console, network, network_full, html, or log. Required, so a drill-down never returns more than you asked for. ’network’ ranks the resources (failures, non-2xx, and the slowest 20) with the totals beside them; ’network_full’ returns every one. |
projectId |
string | yes | |
scriptRunId |
string | yes | The script run id returned by play_script. |
selector |
string | no | Optional CSS selector, for the ‘html’ part only. Without it, html returns an outline of the page’s anchorable elements with a suggested selector for each — ask for that first when you don’t know what to target. With it, html returns the matching elements’ outerHTML. |
stepIndexes |
array of integer | yes | The step indexes to drill into, starting at 1, as reported by get_play_status. |
import_script
Import Script · Write · readOnlyHint: false · destructiveHint: false · idempotentHint: false · openWorldHint: false
Import an open-source load test (JMeter .jmx, k6 .js, or Locust .py) into an existing script, converting it to Loadster commands. An import may create script assets, datasets, and a scenario; replace=true also replaces the script’s existing commands and variables. Returns action items to review. For OpenAPI/Swagger or Postman, read the spec yourself and build commands with create_script instead.
| Parameter | Type | Required | Description |
|---|---|---|---|
baseUrl |
string | no | Optional base URL to prefix relative requests. |
content |
string | yes | The source file content (the .jmx XML, .js, or .py text). |
projectId |
string | yes | |
replace |
boolean | no | Replace existing commands (true) or append to them (false). Defaults to false. |
scriptId |
string | yes | The script id to import into (create an empty script first). |
source |
string | yes | The source tool: jmeter, k6, or locust. |
list_projects
List Projects · Read · readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false
List the Loadster projects the current token can access, each with its id and name. Every other tool takes one of these ids. When the team has no projects, the result says so and points at create_project. Prefer an existing project: call list_projects first, and create a new one only if the team has none or the user explicitly asked for one. When unsure, ask the user before creating.
This tool takes no parameters.
list_script_assets
List Script Assets · Read · readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false
List the files attached to a script (request bodies, upload files, Playwright support files). Each path is the key a command references.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId |
string | yes | |
scriptId |
string | yes |
list_script_revisions
List Script Revisions · Read · readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false
List a script’s past revisions (newest first) with version, save time, author, and step count.
| Parameter | Type | Required | Description |
|---|---|---|---|
count |
integer | no | How many revisions to return (default 10, maximum 100). |
projectId |
string | yes | |
scriptId |
string | yes |
list_scripts
List Scripts · Read · readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false
List the scripts in a project with their id, name, bot type, step count, and current revision version (without the full command list).
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId |
string | yes |
play_script
Play Script · Sensitive write · readOnlyHint: false · destructiveHint: false · idempotentHint: false · openWorldHint: true
Start playing a saved script. Returns immediately with a run id and a queued status, since a play can take anywhere from a few seconds (HTTP) to several minutes (browser or Playwright); read the results with get_play_status.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId |
string | yes | |
scriptId |
string | yes | The script id to play. |
skipWaitTimes |
boolean | no | Skip wait/think times for a faster run. Defaults to false. |
put_script_asset
Put Script Asset · Sensitive write · readOnlyHint: false · destructiveHint: true · idempotentHint: false · openWorldHint: false
Upload or replace a script asset from base64 content. Use the path as the key a command references — e.g. set an HTTP command’s requestBody to { “key”: “<path>” } to give it a request body, or list the path in a browser upload step’s files.
| Parameter | Type | Required | Description |
|---|---|---|---|
contentBase64 |
string | yes | The file content, base64-encoded. |
path |
string | yes | The asset path / key to store it under, e.g. ‘body.json’. |
projectId |
string | yes | |
scriptId |
string | yes |
restore_script_revision
Restore Script Revision · Write · readOnlyHint: false · destructiveHint: false · idempotentHint: false · openWorldHint: false
Restore a script to a past revision, saving that revision’s commands as a new revision.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId |
string | yes | |
scriptId |
string | yes | |
version |
integer | yes | The revision version number to restore. |
stop_script
Stop Script · Write · readOnlyHint: false · destructiveHint: false · idempotentHint: true · openWorldHint: false
Stop a running play. Errors if the run does not exist; once the stop takes effect, get_play_status reports the run as stopped.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId |
string | yes | |
scriptRunId |
string | yes | The script run id to stop. |
update_script
Update Script · Write · readOnlyHint: false · destructiveHint: false · idempotentHint: false · openWorldHint: false
Update an existing script. Each of name, type, commands, and variables is optional: a field left out keeps its stored value, an empty list clears that list, and a non-empty list replaces the whole list, never merging into it. A script’s type cannot be changed: type, if sent, must match the script’s bot type, so to switch types create a new script of the desired type instead. Sending commands or variables saves a new revision; a name alone renames the script. Read the script with get_script before changing it, never rebuild it from list_scripts. Every write against a user’s existing data needs their explicit confirmation first.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId |
string | yes | |
script |
object | yes | The fields to change: name, type, commands, and variables. Leave a field out to keep it. type, if sent, must be the script’s current type; a different type is rejected. |
scriptId |
string | yes |
Script Authoring Tools
get_command_schema
Get Command Schema · Read · readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false
Get the recursive schema for one command type, so you can build a valid command object. Some fields carry a ’notes’ string describing accepted keys that aren’t reflectable, such as element action options and locator attributes.
| Parameter | Type | Required | Description |
|---|---|---|---|
commandType |
string | yes | The command type, e.g. ‘http’, ’navigate’, or ’element’. |
get_example
Get Example Script · Read · readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false
Get a small, valid worked example script for a bot type to use as a starting point.
| Parameter | Type | Required | Description |
|---|---|---|---|
botType |
string, one of HTTP, BROWSER, PLAYWRIGHT |
yes | The bot type. HTTP is a Protocol Bot script, BROWSER is a Browser Bot script, and PLAYWRIGHT is a Playwright script. “Browser script” is ambiguous: Browser Bot and Playwright are different types, so if the user’s wording doesn’t say which, ask before creating. |
get_scripting_api
Get Scripting API · Read · readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false
List the scripting API scopes (bot, http, browser, …) available in code blocks, or fetch one scope’s members with their signatures and docs.
| Parameter | Type | Required | Description |
|---|---|---|---|
scope |
string | no | The scope name, e.g. ‘bot’ or ‘http’. Omit to list the available scopes. |
get_variable_schema
Get Variable Schema · Read · readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false
Get the schema for binding a script variable to a dataset, including the accepted update and selection strategies. A variable is a named row cursor bound to one whole dataset by dataSetId: on each pull it holds an entire row, advancing per occurrence, per iteration, or per bot (‘vuser’) depending on updateStrategy, with rows taken sequentially or randomly per selectionStrategy. Reference it as ${name} in command fields or bot.getVariable(’name’) in Playwright code. After changing bindings or references, run validate_script to cross-check them.
This tool takes no parameters.
list_command_types
List Command Types · Read · readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false
List the command (step) types available for a bot type, with a description and the bot types each applies to. Use this before authoring commands.
| Parameter | Type | Required | Description |
|---|---|---|---|
botType |
string, one of HTTP, BROWSER, PLAYWRIGHT |
no | The bot type, or omit to list all types. HTTP is a Protocol Bot script, BROWSER is a Browser Bot script, and PLAYWRIGHT is a Playwright script. “Browser script” is ambiguous: Browser Bot and Playwright are different types, so if the user’s wording doesn’t say which, ask before creating. |
validate_script
Validate Script · Read · readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false
Structurally validate a list of commands for a bot type before saving or playing, reporting any issues by command index. Pass the script’s variables as well and it also cross-checks the bindings against the ${…} and bot.getVariable reads in the commands, warning about a read nothing supplies, a binding nothing reads, and a per-occurrence variable read more than once in an iteration. Warnings never make a script invalid and never stop a save — all three are legal scripts.
| Parameter | Type | Required | Description |
|---|---|---|---|
botType |
string, one of HTTP, BROWSER, PLAYWRIGHT |
yes | The bot type the commands are for. HTTP is a Protocol Bot script, BROWSER is a Browser Bot script, and PLAYWRIGHT is a Playwright script. “Browser script” is ambiguous: Browser Bot and Playwright are different types, so if the user’s wording doesn’t say which, ask before creating. |
commands |
array of object | yes | The commands to validate, each a JSON object with a ’type’. |
variables |
array of object | no | The script’s variable bindings, as get_script returns them. Omit to skip the binding cross-check and validate structure alone. |
Dataset Tools
append_dataset_rows
Append Dataset Rows · Write · readOnlyHint: false · destructiveHint: false · idempotentHint: false · openWorldHint: false
Add rows to the end of an existing dataset, sending only the new rows — the rows already in the table stay as they are, so there is no need to read them first. Every row must have as many columns as the table already has; a row that doesn’t is rejected and nothing at all is written. Appending to an empty dataset takes the column count from the first row.
| Parameter | Type | Required | Description |
|---|---|---|---|
datasetId |
string | yes | |
projectId |
string | yes | |
rows |
array of array | yes | The rows to add to the end of the table (data rows only — no header row). Each row must have the same number of columns as the dataset. |
create_dataset
Create Dataset · Write · readOnlyHint: false · destructiveHint: false · idempotentHint: false · openWorldHint: false
Create a new dataset in a project. Loadster treats every row as data and addresses columns by zero-based index — a header row would be fed to bots like any other row, so don’t add one when authoring values. Unless the user explicitly asked for a dataset, confirm with them before creating one.
| Parameter | Type | Required | Description |
|---|---|---|---|
dataset |
object | yes | The dataset name and table of values (data rows only — no header row). |
projectId |
string | yes |
delete_dataset
Delete Dataset · Sensitive write · readOnlyHint: false · destructiveHint: true · idempotentHint: false · openWorldHint: false
Delete a dataset from a project.
| Parameter | Type | Required | Description |
|---|---|---|---|
datasetId |
string | yes | |
projectId |
string | yes |
get_dataset
Get Dataset · Read · readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false
Get a single dataset’s shape — name, row and column counts, dashboard link — plus a leading window of its rows: the first five in table order by default, more with offset and limit. Compare rowOffset and the rows returned against rowCount to see how much you are not looking at. Loadster serves every row to bots, but a user’s imported data may still start with a header-looking row — don’t assume either way; ask before treating or removing it.
| Parameter | Type | Required | Description |
|---|---|---|---|
datasetId |
string | yes | |
limit |
integer | no | How many rows to return (default 5, maximum 100). Page through a larger table by raising offset. |
offset |
integer | no | Zero-based index of the first row to return (default 0). |
projectId |
string | yes |
list_datasets
List Datasets · Read · readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false
List the datasets in a project with their id, name, and row/column counts (without the full value table).
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId |
string | yes |
update_dataset
Update Dataset · Sensitive write · readOnlyHint: false · destructiveHint: true · idempotentHint: false · openWorldHint: false
Replace an existing dataset’s name and values — the values given become the entire table, so send the complete table including every row you want to keep. To add rows, call append_dataset_rows instead.
| Parameter | Type | Required | Description |
|---|---|---|---|
dataset |
object | yes | The new dataset name and table of values (data rows only — no header row). |
datasetId |
string | yes | |
projectId |
string | yes |
Load Test Scenario Tools
create_scenario
Create Scenario · Write · readOnlyHint: false · destructiveHint: false · idempotentHint: false · openWorldHint: false
Create a scenario in a project — saving costs nothing and starts nothing, so hand the user the dashboard link and let them launch it. The save is refused for a loadEngineId list_engines doesn’t offer, a stage shorter than the minimum, or more bots or populations than the account allows, and the refusal names the limit. The summary’s launchBlockers are reasons the user could not launch it right now; they never stop the save, so tell the user about a blocker instead of rewriting the scenario to avoid it. The ’load-test-scenarios’ topic covers what the stages and ramps actually do.
| Parameter | Type | Required | Description |
|---|---|---|---|
name |
string | yes | The scenario name. |
populations |
array of object | yes | The Populations, in order. Each needs a name, the scriptId of a script in this project, and stages — { target, duration, ramp } segments that run for duration milliseconds and reach target bots by the end, each starting from where the previous stage left off. Optional per population: id (send back the id get_scenario reported to keep a population’s identity), loadEngineId (an id from list_engines; defaults to the account’s default region), iterations, iterationsPerUser, aggressionMultiplier, and playbackOptions with connectionBps (bits per second), hostnameOverrides, and variableOverrides. Read get_documentation topic ’load-test-scenarios’ for what stages and ramps do; list_engines carries the account’s stage bounds and bot caps. |
projectId |
string | yes |
delete_scenario
Delete Scenario · Sensitive write · readOnlyHint: false · destructiveHint: true · idempotentHint: false · openWorldHint: false
Delete a scenario from a project. The scripts its populations referenced are left alone.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId |
string | yes | |
scenarioId |
string | yes |
get_scenario
Get Scenario · Read · readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false
Get a single scenario including its Populations, plus a dashboard link and its launch readiness — an empty launchBlockers means the user can launch it as it stands. A field left out of a population is at its default: iterations and iterationsPerUser unlimited, aggressionMultiplier 1.0, and bandwidth unthrottled. Read get_documentation topic ’load-test-scenarios’ for what the stages and ramps actually do.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId |
string | yes | |
scenarioId |
string | yes |
list_scenarios
List Scenarios · Read · readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false
List the scenarios in a project with their id, name, version, population count, peak bots, and total duration in milliseconds — without the populations, fuel estimate, and launch blockers get_scenario reports. A Scenario is a saved load test configuration: a named list of Populations (the Dashboard calls them “bot groups”), each of which runs one script with its own load shape on one engine or region. Saving a scenario costs nothing and runs nothing; a user launches it from the Dashboard.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId |
string | yes |
update_scenario
Update Scenario · Sensitive write · readOnlyHint: false · destructiveHint: true · idempotentHint: false · openWorldHint: false
Replace an existing scenario’s name and Populations — the populations given become the whole scenario, so to change one, send the others alongside it, each with the id get_scenario reported, or they are dropped and the ones you send are new populations. The same save rules and summary as create_scenario apply.
| Parameter | Type | Required | Description |
|---|---|---|---|
name |
string | yes | The new scenario name. |
populations |
array of object | yes | The Populations, in order. Each needs a name, the scriptId of a script in this project, and stages — { target, duration, ramp } segments that run for duration milliseconds and reach target bots by the end, each starting from where the previous stage left off. Optional per population: id (send back the id get_scenario reported to keep a population’s identity), loadEngineId (an id from list_engines; defaults to the account’s default region), iterations, iterationsPerUser, aggressionMultiplier, and playbackOptions with connectionBps (bits per second), hostnameOverrides, and variableOverrides. Read get_documentation topic ’load-test-scenarios’ for what stages and ramps do; list_engines carries the account’s stage bounds and bot caps. |
projectId |
string | yes | |
scenarioId |
string | yes |
Engine Tools
list_engines
List Engines · Read · readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false
List everywhere a population can run, with the customer’s own limits a scenario is written against. Each entry’s id is what a population’s loadEngineId names — never invent one. Type CLOUD is a single Loadster cloud region, WILDCARD is a pattern (’north-america-’, ‘’) that lets Loadster pick a region inside it when the test launches, and PRIVATE is one of the customer’s own Loadster Engines, the only kind that can reach a host on their network. The per-population caps and stage bounds are enforced when a scenario is saved; capacities, locked regions, and the per-region and per-engine caps matter only at launch and never stop a save. While limits.freeTrialCustomer is true, an entry with locked true can be saved onto but not launched from, so put a trial’s populations on an entry with locked false and keep the scenario’s peak within limits.maxFreeTrialBotsPerTest.
This tool takes no parameters.
Load Test Report Tools
get_load_test_report
Get Load Test Report · Read · readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false
Get a finished Load Test’s Test Report — aggregate totals, the error and advice picture behind the Dashboard’s advice tile, and per-Population outcomes; an unfinished test answers with an error naming its status. The advice buckets and detection flags are heuristics, not a diagnosis of this test: where the totals, percentiles, per-URL counts and Populations contradict a bucket or a flag, or show something it never names, say so and follow the data. Before advising the user, read the get_documentation topic ‘analyzing-test-results’ and cross-read the Scenario and the played Scripts, so your advice names concrete elements — a specific URL, Population, bot count, or script step — instead of repeating the error buckets back.
| Parameter | Type | Required | Description |
|---|---|---|---|
errorUrlLimit |
integer | no | How many URLs to return in errorsByUrl, worst first (default 10, no maximum). There is no offset, so read the tail by raising this. |
projectId |
string | yes | |
testId |
string | yes | The load test id, as reported by list_load_tests. |
list_load_tests
List Load Tests · Read · readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false
List a project’s finished Load Tests, newest first, a window of summary rows at a time. A Load Test is a run of a Scenario at scale by many bots; the user launches one from the Dashboard, it appears here once it finishes, and nothing on this surface launches, stops, or deletes one. Read one test’s Test Report with get_load_test_report.
| Parameter | Type | Required | Description |
|---|---|---|---|
limit |
integer | no | How many tests to return (default 10, maximum 50). |
offset |
integer | no | Zero-based index of the first test to return (default 0). |
projectId |
string | yes |
update_load_test_notes
Update Load Test Notes · Sensitive write · readOnlyHint: false · destructiveHint: true · idempotentHint: true · openWorldHint: false
Replace the notes on a finished Load Test’s Test Report — the only writable thing on a Load Test. Ask the user before writing: notes belong to the user, and advising on a test never requires writing them. The text sent becomes the report’s entire notes, so first read the current notes with get_load_test_report and preserve the user’s content in what you send.
| Parameter | Type | Required | Description |
|---|---|---|---|
notes |
string | yes | The full notes text to store on the Test Report, replacing whatever notes it already carries. At most 4096 characters; an empty string clears the notes. |
projectId |
string | yes | |
testId |
string | yes | The load test id, as reported by list_load_tests. |
Monitoring and Incident Tools
create_monitor
Create Monitor · Write · readOnlyHint: false · destructiveHint: false · idempotentHint: false · openWorldHint: false
Create a Monitor in a project — always disabled, and nothing on this surface can enable one. An enabled Monitor consumes fuel on its schedule, unattended, so enabling is the user’s act in the Dashboard, at the link the returned summary carries. Read the ‘monitoring’ topic before choosing a frequency or thresholds.
| Parameter | Type | Required | Description |
|---|---|---|---|
engineIds |
array of string | yes | The ids of the monitoring locations the Cycles run from, as list_monitoring_locations reports them; at least one is required. Monitoring locations are their own set, not the load test regions list_engines offers, and an unknown id is refused with an error naming the valid ones. |
failureThreshold |
integer | no | Consecutive failed Cycles before an Incident opens (1 to 128; default 1). |
frequency |
integer | yes | How often a Cycle runs, in milliseconds: 60000 (one minute) to 86400000 (one day). |
name |
string | yes | The monitor name. |
projectId |
string | yes | |
recoveryThreshold |
integer | no | Consecutive passing Cycles before an open Incident closes (1 to 128; default 1). |
scriptId |
string | yes | The id of the Script in this project the Monitor plays each Cycle. |
tags |
array of string | no | Tag names to organize the Monitor. Prefer the names other Monitors already carry, as list_monitors reports them — a name that doesn’t exist yet becomes a new tag, so don’t invent tags the user didn’t ask for. Omit for no tags. |
thresholds |
object | no | The acceptable-metric limits a Cycle is judged against, each optional within the object: responseTimeAverageMin/Max, responseTimeTotalMin/Max, cycleDurationMin/Max, timeToFirstByteMax, firstContentfulPaintMax, largestContentfulPaintMax, and totalBlockingTimeMax in milliseconds; cumulativeLayoutShiftMax as the unitless Web Vitals score; performanceScoreMin as the 0-100 floor. A limit left out is not checked; omit the whole object to check none. |
delete_monitor
Delete Monitor · Sensitive write · readOnlyHint: false · destructiveHint: true · idempotentHint: false · openWorldHint: false
Delete a Monitor from a project. Its Incidents are deleted with it and it is removed from any status pages; the Script it played is left alone. To stop a Monitor running without losing it, use disable_monitor instead.
| Parameter | Type | Required | Description |
|---|---|---|---|
monitorId |
string | yes | |
projectId |
string | yes |
disable_monitor
Disable Monitor · Write · readOnlyHint: false · destructiveHint: false · idempotentHint: true · openWorldHint: false
Disable a Monitor, stopping its scheduled Cycles and their fuel burn; disabling closes the Monitor’s open Incidents. Idempotent, and the only enabled-state transition this surface offers — re-enabling is the user’s act in the Dashboard, at the link the returned summary carries.
| Parameter | Type | Required | Description |
|---|---|---|---|
monitorId |
string | yes | |
projectId |
string | yes |
get_incident
Get Incident · Read · readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false
Get a single Incident: when it opened and closed, every notification that went out with its delivery outcome, the status events recorded on it, and the ids of the Cycles that opened and closed it. To reconstruct what happened, read those Cycles with get_monitor_cycle_detail, and cross-read the Monitor’s configuration and its Script so the diagnosis names the concrete step, URL, or threshold at fault rather than a vague symptom. The ‘monitoring’ topic covers advising on thresholds or noise.
| Parameter | Type | Required | Description |
|---|---|---|---|
incidentId |
string | yes | The incident id, as reported by list_incidents. |
projectId |
string | yes |
get_monitor
Get Monitor · Read · readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false
Get a single Monitor’s full configuration and dashboard link. Configuration only — a Monitor’s steps are its Script’s commands, so read them with get_script. Whether a Monitor runs is the user’s call: enabling happens in the Dashboard at the link, never through this surface. The ‘monitoring’ topic covers what a Monitor’s configuration should be.
| Parameter | Type | Required | Description |
|---|---|---|---|
monitorId |
string | yes | |
projectId |
string | yes |
get_monitor_cycle_detail
Get Monitor Cycle Detail · Read · readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false
Get one Cycle in full: status, failure message, the engine it ran from, timestamps, and every metric the Monitor’s thresholds judge. Its scriptRunId is a played run like any other — pass it with the project id to get_play_status for per-step results and get_step_detail for the exact request and response that failed — and it names the scriptId it checked, so cross-read the Script and point advice at a concrete step or URL. Works with a cycle id from list_monitor_cycles or from an Incident’s cycle references. The ‘monitoring’ topic covers what the thresholds should be.
| Parameter | Type | Required | Description |
|---|---|---|---|
cycleId |
string | yes | The cycle id, as reported by list_monitor_cycles or an Incident’s cycle references. |
projectId |
string | yes |
get_monitoring_summary
Get Monitoring Summary · Read · readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false
Get the Monitoring Summary for a project: the aggregate health picture across its Monitors over a period, defaulting to the last 7 days, with per-Monitor and per-day aggregates for trends (times in seconds; performance score 0-100). Drill down instead of asking for more: list_incidents for what opened and closed in the period, list_monitor_cycles for one Monitor’s individual Cycles. Read the ‘monitoring’ topic before interpreting uptime or health for the user.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId |
string | yes | |
since |
string | no | Start of the period, ISO-8601 (2026-08-19 or 2026-08-19T00:00:00Z). Defaults to seven days before until. |
until |
string | no | End of the period, ISO-8601. Defaults to now. |
list_incidents
List Incidents · Read · readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false
List a project’s Incidents — open ones first, then the most recently closed; unresolved only by default, with includeResolved for incident archaeology over a since/until window and monitorId to ask about one Monitor. An Incident opens when a Monitor’s consecutive failing Cycles reach its failure threshold, and closes after enough consecutive passes, or when the Monitor is disabled. Rows are lean; read one Incident’s notifications, statuses, and cycle references with get_incident. The ‘monitoring’ topic covers how Incidents notify.
| Parameter | Type | Required | Description |
|---|---|---|---|
includeResolved |
boolean | no | Include resolved Incidents too. Defaults to false: only open Incidents. |
limit |
integer | no | How many Incidents to return (default 10, maximum 50). |
monitorId |
string | no | Only this Monitor’s Incidents, as reported by list_monitors. |
projectId |
string | yes | |
since |
string | no | Only Incidents still active after this ISO-8601 instant (2026-08-26T00:00:00Z) or date (2026-08-26). |
until |
string | no | Only Incidents opened at or before this ISO-8601 instant or date. |
list_monitor_cycles
List Monitor Cycles · Read · readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false
List a Monitor’s Cycles, newest first — one row per Cycle with its status, timestamps, the engine id it ran from, and headline response times; a Cycle with no status yet is scheduled or still running. Window with since/until and limit to spot patterns — flapping around a threshold, slow drift, failures from one region — then drill into one Cycle’s full metrics and failure message with get_monitor_cycle_detail. The ‘monitoring’ topic explains what each status means.
| Parameter | Type | Required | Description |
|---|---|---|---|
limit |
integer | no | How many Cycles to return (default 20, maximum 100). |
monitorId |
string | yes | |
projectId |
string | yes | |
since |
string | no | Only Cycles scheduled at or after this ISO-8601 instant (2026-08-26T00:00:00Z) or date (2026-08-26). |
until |
string | no | Only Cycles scheduled before this ISO-8601 instant or date (exclusive). |
list_monitoring_locations
List Monitoring Locations · Read · readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false
List everywhere a Monitor’s Cycles can run from. Each entry’s id is what a Monitor’s engineIds names — never invent one. Type CLOUD is one of Loadster’s shared monitoring locations, and PRIVATE is one of the customer’s own Loadster Engines, the only kind that can reach a host on their network. Monitoring locations are their own set, not the load test regions list_engines offers. Read this before create_monitor or update_monitor.
This tool takes no parameters.
list_monitors
List Monitors · Read · readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false
List the Monitors in a project. A Monitor is a scheduled, low-volume check that runs a Script on a frequency to verify health and alert on failure; each execution is a Cycle. Each row is a summary without the thresholds and engine ids; read one Monitor’s full configuration with get_monitor. Read get_documentation topic ‘monitoring’ for how Monitors, Cycles, and Incidents behave.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId |
string | yes |
update_monitor
Update Monitor · Sensitive write · readOnlyHint: false · destructiveHint: true · idempotentHint: false · openWorldHint: false
Replace an existing Monitor’s exposed configuration: name, Script, frequency, engine ids, failure and recovery thresholds, tags, and the acceptable-metric thresholds. An omitted threshold is cleared and omitted tags are removed, so read the current configuration with get_monitor first and send everything that should remain. Everything outside those fields is untouched: an update never changes whether the Monitor is enabled, and never touches its notification policies or maintenance windows, so a config edit cannot stop a running Monitor, start a stopped one, or unhook the user’s alerting.
| Parameter | Type | Required | Description |
|---|---|---|---|
engineIds |
array of string | yes | The ids of the monitoring locations the Cycles run from, as list_monitoring_locations reports them; at least one is required. Monitoring locations are their own set, not the load test regions list_engines offers, and an unknown id is refused with an error naming the valid ones. |
failureThreshold |
integer | no | Consecutive failed Cycles before an Incident opens (1 to 128; default 1). |
frequency |
integer | yes | How often a Cycle runs, in milliseconds: 60000 (one minute) to 86400000 (one day). |
monitorId |
string | yes | |
name |
string | yes | The new monitor name. |
projectId |
string | yes | |
recoveryThreshold |
integer | no | Consecutive passing Cycles before an open Incident closes (1 to 128; default 1). |
scriptId |
string | yes | The id of the Script in this project the Monitor plays each Cycle. |
tags |
array of string | no | Tag names to organize the Monitor. Prefer the names other Monitors already carry, as list_monitors reports them — a name that doesn’t exist yet becomes a new tag, so don’t invent tags the user didn’t ask for. Omit for no tags. |
thresholds |
object | no | The acceptable-metric limits a Cycle is judged against, each optional within the object: responseTimeAverageMin/Max, responseTimeTotalMin/Max, cycleDurationMin/Max, timeToFirstByteMax, firstContentfulPaintMax, largestContentfulPaintMax, and totalBlockingTimeMax in milliseconds; cumulativeLayoutShiftMax as the unitless Web Vitals score; performanceScoreMin as the 0-100 floor. A limit left out is not checked; omit the whole object to check none. |
Manual Tools
get_documentation
Get Documentation · Read · readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false
List the Loadster manual’s topics with their keys and URLs, or read up to 3 topics’ text by key. Pass one key as topic, or up to 3 keys as topics. Omit both to list every topic.
| Parameter | Type | Required | Description |
|---|---|---|---|
maxLength |
integer | no | Characters to return per topic. Defaults to 25000. |
startIndex |
integer | no | Character offset to resume one topic from, taken from a previous call’s nextStartIndex. |
topic |
string | no | A single topic key, e.g. ‘monitoring’ or the nested ‘playwright-scripts/bot’. Same as passing that one key in topics. Omit, and omit topics, to list every topic. |
topics |
array of string | no | Up to 3 topic keys, e.g. ‘dynamic-datasets’ or the nested ‘playwright-scripts/bot’. Omit, and omit topic, to list every topic. |
Feedback Tool
submit_feedback
Submit Feedback · Write · readOnlyHint: false · destructiveHint: false · idempotentHint: false · openWorldHint: false
Optional. Sends a note about this tool surface to the Loadster team, who read it to fix what the surface got wrong. Nothing requires it and no task depends on it. A note is about the tools themselves: what worked, what was missing or confusing, what needed a workaround. It should not carry conversation data: the user’s prompts, their credentials, or anything from their account. Feedback is at most 2000 characters; a longer submission is rejected rather than truncated.
| Parameter | Type | Required | Description |
|---|---|---|---|
feedback |
string, at most 2000 characters | yes | What worked and what did not about the tools, in at most 2000 characters. |
outcome |
string, one of SUCCESS, PARTIAL, FAILURE |
yes | How the task ended. |
taskDescription |
string, at most 200 characters | no | The kind of task the note is about, in your own summary rather than the user’s wording, in at most 200 characters. |