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, 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_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.
  • 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 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.