Manual

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, Sensitive Write, and Execute MCP Tools

Every tool carries the four standard MCP behavior hints (readOnlyHint, destructiveHint, idempotentHint, and openWorldHint), and Loadster sorts each tool into one of four classes:

  • 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.
  • Execute tools start or stop something that burns fuel or uses your plan: launching a load test, stopping it, and enabling a monitor. Launching and enabling carry the same hints as a sensitive write, so an assistant that asks before sensitive writes asks you before each launch or enable.

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.

A connection or token sees only the tools its access level allows. Read sees the Read tools, Read+Write adds the Write and Sensitive Write tools, and Read+Write+Execute sees them all. You choose the level when you connect an assistant or create a personal access token.

What Loadster MCP Tools Can’t Do

Some things are left to humans in the Loadster dashboard. No MCP tool manages notification policies, maintenance windows, your team, or billing. Launching or stopping a load test and enabling a monitor exist only at the Read+Write+Execute access level; at the other levels an assistant saves the scenario and you launch it yourself, and monitors are created disabled for you to enable. A launch goes through the same checks as the dashboard’s Launch button, and when a scenario can’t launch the assistant gets the same reasons instead of a running test.

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:

  • Tool calls: each person can make 120 tool calls a minute in each team. Three tools have a tighter limit of their own: play_script allows 30 calls every 2 minutes, get_load_test_report allows 30 a minute, and get_load_test_status allows 20 a minute. An assistant’s OAuth connection and your personal access tokens count toward the same limits. A call over a limit returns a tool error that says how long to wait, and the tool doesn’t run.
  • Script plays: each person and each team can only have a limited number of scripts playing at once. When that limit is reached, play_script returns an error until a play finishes or is stopped with stop_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, and of scripts and datasets in a project.
  • 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.

MCP calls 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 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.
tags array of string no Tag names; a name the team doesn’t have yet becomes a new tag. Omit for no tags.

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 · Sensitive Write · readOnlyHint: false · destructiveHint: true · 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, current revision version, and tag names (without the full command list). Tags are shared across the team: to tag an item, reuse a name the list tools already report, and create a new tag only when the user asks for one.

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, variables, and tags 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 or tags alone save no revision. 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 no The fields to change: name, type, commands, and variables. Leave a field out to keep it, or omit script to change only the tags. type, if sent, must be the script’s current type; a different type is rejected.
scriptId string yes
tags array of string no Tag names; a name the team doesn’t have yet becomes a new tag. Omit to keep the current tags; send [] to clear them.

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
tags array of string no Tag names; a name the team doesn’t have yet becomes a new tag. Omit for no tags.

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, tag names, 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, row/column counts, and tag names (without the full value table). Tags are shared across the team: to tag an item, reuse a name the list tools already report, and create a new tag only when the user asks for one.

Parameter Type Required Description
projectId string yes

update_dataset

Update Dataset · Sensitive Write · readOnlyHint: false · destructiveHint: true · idempotentHint: false · openWorldHint: false

Update an existing dataset. Each of name, values, and tags is optional: a field left out keeps its stored value, so a rename leaves the table alone. Values sent become the entire table, so send the complete table including every row you want to keep; an empty table clears the rows. To add rows, call append_dataset_rows instead.

Parameter Type Required Description
dataset object no The fields to change: name and the table of values (data rows only — no header row). Leave a field out to keep it, or omit dataset to change only the tags.
datasetId string yes
projectId string yes
tags array of string no Tag names; a name the team doesn’t have yet becomes a new tag. Omit to keep the current tags; send [] to clear them.

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. Launch it with launch_load_test at the “Read+Write+Execute” access level; below that level the tool is absent, and the user launches it from the Dashboard at the link. The save is refused for an engineId 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), engineId (an id from list_engines; defaults to the account’s default region; loadEngineId is its deprecated alias), 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
tags array of string no Tag names; a name the team doesn’t have yet becomes a new tag. Omit for no tags.

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: the account’s fuelBalance; launchBlockers, where an empty list means it can launch as it stands; and estimatedFuelLow and estimatedFuelHigh, the low and high ends of the Fuel estimate the Dashboard shows. The estimate is present whenever the test would burn Fuel, which is every test on an account without a plan, and on one with a plan, any test the plan does not cover; launch_load_test then runs the whole test on Fuel. Without an estimate, it runs on the account’s plan and burns no Fuel. get_documentation topic ‘faqs/plan-or-fuel’ explains when a plan or Fuel applies. 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

launch_load_test

Launch Load Test · Execute · readOnlyHint: false · destructiveHint: true · idempotentHint: false · openWorldHint: true

Launch a saved Scenario as a Load Test, exactly as stored. Its Populations send real traffic to the user’s site. Like the Dashboard’s Launch button, it runs on the account’s plan when get_scenario shows no Fuel estimate and runs the whole test on Fuel when it shows one. Read the Scenario with get_scenario first, tell the user the Fuel estimate range and the fuelBalance, or that the plan covers it when there is no estimate, and launch only with the user’s approval. If the plan can’t run the test right now, the refusal gives the reason and burns no Fuel, and the user can try to launch from the Dashboard instead. If the call times out, check list_load_tests before launching again. A Scenario with launchBlockers is refused, and the refusal lists them. Trial, plan, Fuel and other checks apply as in the Dashboard, and a refusal carries their message. The result carries the new Load Test’s id, its stage and the Dashboard link; follow it with get_load_test_status and stop it with stop_load_test.

Parameter Type Required Description
label string no A label stored with the Load Test. Leave it out for none.
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, total duration in milliseconds, and tag names — 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. Launch it with launch_load_test at the “Read+Write+Execute” access level; below that level the tool is absent, and the user launches it from the Dashboard. Tags are shared across the team: to tag an item, reuse a name the list tools already report, and create a new tag only when the user asks for one.

Parameter Type Required Description
projectId string yes

update_scenario

Update Scenario · Sensitive Write · readOnlyHint: false · destructiveHint: true · idempotentHint: false · openWorldHint: false

Update an existing scenario. Each of name, populations, and tags is optional: a field left out keeps its stored value. Populations sent replace the whole list, never merging into it, 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 no The new scenario name. Leave it out to keep the current name.
populations array of object no 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), engineId (an id from list_engines; defaults to the account’s default region; loadEngineId is its deprecated alias), 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
tags array of string no Tag names; a name the team doesn’t have yet becomes a new tag. Omit to keep the current tags; send [] to clear them.

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 engineId 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, per-Population outcomes, and each engine’s average and peak CPU; 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.
loadTestId string no The load test id, as reported by list_load_tests. Required unless the deprecated testId is sent.
projectId string yes
testId string no Deprecated alias of loadTestId; send loadTestId instead.

get_load_test_status

Get Load Test Status · Read · readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

Get a Load Test’s live status, as the Dashboard’s live test view shows it: stage, elapsed time, Bots started, running, peak and planned per Population, Iterations, response time percentiles, throughput, errors by type, and each engine’s region, online state and, while the test runs, current CPU percentage. Use it to tell the user how a test in progress is going, and to tell an overloaded engine from a slow target. Call it no more often than every 10 seconds; the numbers do not move faster than that. Once the test is over, the status says so in its note; stop polling and read the Test Report with get_load_test_report.

Parameter Type Required Description
loadTestId string yes The load test id, as reported by list_load_tests.
projectId string yes

get_load_test_url_timings

Get Load Test URL Timings · Read · readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

Get a finished Load Test’s response times per URL, slowest first by the total time all hits to the URL took: hits, average, minimum and maximum response time, and average time to first byte, in milliseconds. Use it to name the slow pages behind the percentiles in get_load_test_report. Compare urlOffset and the URLs returned against totalUrls to see how much you have not read; page on with offset.

Parameter Type Required Description
limit integer no How many URLs to return (default 20, maximum 100).
loadTestId string yes The load test id, as reported by list_load_tests.
offset integer no Zero-based index of the first URL to return (default 0).
projectId string yes

list_load_tests

List Load Tests · Read · readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

List a project’s Load Tests, a window of summary rows at a time: the ones in progress first, each with its stage, then the finished ones, newest first. A Load Test is a run of a Scenario at scale by many bots; launch_load_test launches one and stop_load_test stops one, at the “Read+Write+Execute” access level; below that level both are absent and the user does it in the Dashboard. Nothing on this surface deletes one. Follow a test in progress with get_load_test_status; read a finished 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

stop_load_test

Stop Load Test · Execute · readOnlyHint: false · destructiveHint: false · idempotentHint: true · openWorldHint: false

Stop a Load Test. By default the stop is graceful, as the Dashboard’s Stop button does: each bot finishes the iteration it is on before it stops, so the last iterations complete and are reported in full. With immediate set to true the Load Test is killed instead: bots stop mid-iteration, cutting their last iterations short, and the test ends sooner. Stop gracefully unless the user asks to kill the test or the target needs relief now; a Load Test already STOPPING gracefully can still be killed with immediate. A running Load Test moves to STOPPING and then ends; one that has not started yet is canceled either way. A Load Test that has already ended is refused. The result carries its stage after the stop; follow it with get_load_test_status, and read the Test Report with get_load_test_report once it has finished.

Parameter Type Required Description
immediate boolean no True to kill the Load Test, stopping bots mid-iteration; false or omitted to stop it gracefully, letting each bot finish its current iteration.
loadTestId string yes The load test id, as reported by list_load_tests or launch_load_test.
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 thing on a Load Test this surface edits. 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
loadTestId string no The load test id, as reported by list_load_tests. Required unless the deprecated testId is sent.
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 no Deprecated alias of loadTestId; send loadTestId instead.

Monitoring and Incident Tools

create_monitor

Create Monitor · Write · readOnlyHint: false · destructiveHint: false · idempotentHint: false · openWorldHint: false

Create a Monitor in a project, initially disabled. An enabled Monitor runs on its schedule, unattended. Its Cycles burn Fuel unless the account has a plan that includes monitoring, which covers them up to its limits. Enable it with enable_monitor at the “Read+Write+Execute” access level; below that level the tool is absent, and the user enables it 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; a name the team doesn’t have yet becomes a new tag. 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 of the object is not checked.

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 the Fuel or plan usage they bring; disabling closes the Monitor’s open Incidents. Idempotent. Re-enable it with enable_monitor at the “Read+Write+Execute” access level; below that level the tool is absent, and the user re-enables it in the Dashboard at the link the returned summary carries.

Parameter Type Required Description
monitorId string yes
projectId string yes

enable_monitor

Enable Monitor · Execute · readOnlyHint: false · destructiveHint: true · idempotentHint: true · openWorldHint: true

Enable a disabled Monitor so its Cycles run on its schedule. Enabling starts a Cycle at once, and the result’s startedCycleId names it; startedCycleId is absent when no Cycle started, because the Monitor was already enabled, recent Cycles reached the limit on immediate Cycles, or the start failed. An enabled Monitor runs Cycles unattended until disable_monitor stops it. Its Cycles burn Fuel unless the account has a plan that includes monitoring, which covers them up to its limits; get_documentation topic ‘faqs/plan-or-fuel’ explains how. Enable only after the user confirms in this conversation. Idempotent: on an enabled Monitor it changes nothing, starts no Cycle, and returns the current state. An unclaimed Trial is refused until the user creates an account.

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. To start a disabled Monitor, call enable_monitor at the “Read+Write+Execute” access level; below that level the tool is absent, and the user enables it in the Dashboard at the link. 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. Tags are shared across the team: to tag an item, reuse a name the list tools already report, and create a new tag only when the user asks for one.

Parameter Type Required Description
projectId string yes

update_monitor

Update Monitor · Sensitive Write · readOnlyHint: false · destructiveHint: true · idempotentHint: false · openWorldHint: false

Update an existing Monitor’s exposed configuration: name, Script, frequency, engine ids, failure and recovery thresholds, tags, and the acceptable-metric thresholds. Each is optional: a field left out keeps its stored value, and a list sent replaces the whole list, never merging into it. The thresholds object works the same way: left out, the limits stay as they are; sent, it replaces all of them, so a limit left out of it is cleared and an empty object clears every limit. Read the current configuration with get_monitor before changing the thresholds. 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. To start a disabled Monitor, call enable_monitor at the “Read+Write+Execute” access level; below that level the tool is absent, and the user enables it in the Dashboard at the returned link.

Parameter Type Required Description
engineIds array of string no 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 no How often a Cycle runs, in milliseconds: 60000 (one minute) to 86400000 (one day).
monitorId string yes
name string no 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 no The id of the Script in this project the Monitor plays each Cycle.
tags array of string no Tag names; a name the team doesn’t have yet becomes a new tag. Omit to keep the current tags; send [] to clear them.
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 of the object is not checked.

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.