Skip to main content
Glama

Scenario runs

run

Start, monitor, list, and retrieve scenario stress-test jobs for portfolio positions, including drawn paths, per-position results, and target-driver forecasts.

Instructions

Runs on the paths of a scenario. Actions: start, status, result, list.

Read guide(name="run-report") first. start draws the scenario's paths and calculates a portfolio's positions — or the positions given in the call — on them, as a job on the runs resource; status reports that job and what the run has written, result the per-position results, the conditional forecast of the targets (forecast.json: P5/P50/P95 of every target driver by month, in its own unit; every driver when targets is omitted) and the report of a portfolio run, list every run of the workspace. base_currency is the base of positions; a portfolio brings its own.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "action": "<action>"
    },
    "name": "run"
  }
}

Input Schema

NameRequiredDescriptionDefault
idNoThe run id that status and result read.
seedNoThe seed of the run: the same scenario, versions and seed give the same numbers.
drawsNoHow many paths the run draws.
actionYesWhat to do: start a run, read its status or result, or list the runs.
targetsNoThe drivers the forecast reports, by id; every driver when omitted. An empty list is refused.
scenarioNoThe scenario the run calculates.
portfolioNoThe stored portfolio the run values; give portfolio or positions, not both.
positionsNoThe positions the run values, given in the call; give portfolio or positions, not both.
base_currencyNoThe currency the notional of positions is stated in, RUB only: the models price against the rouble. A portfolio brings its own.RUB
contributionsNoWhether the report also breaks the loss down by position.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed10 schema fields changedv1.0.2
    • addedInput schema / properties / action / description
      Added value: +"What to do: start a run, read its status or result, or list the runs."
    • addedInput schema / properties / base_currency / description
      Added value: +"The currency the notional of positions is stated in, RUB only: the models price against the rouble. A portfolio brings its own."
    • addedInput schema / properties / contributions / description
      Added value: +"Whether the report also breaks the loss down by position."
    • addedInput schema / properties / draws / description
      Added value: +"How many paths the run draws."
    • addedInput schema / properties / id / description
      Added value: +"The run id that status and result read."
    • addedInput schema / properties / portfolio / description
      Added value: +"The stored portfolio the run values; give portfolio or positions, not both."
    • addedInput schema / properties / positions / description
      Added value: +"The positions the run values, given in the call; give portfolio or positions, not both."
    • addedInput schema / properties / scenario / description
      Added value: +"The scenario the run calculates."
    • addedInput schema / properties / seed / description
      Added value: +"The seed of the run: the same scenario, versions and seed give the same numbers."
    • addedInput schema / properties / targets / description
      Added value: +"The drivers the forecast reports, by id; every driver when omitted. An empty list is refused."
  2. Changed1 schema field changedv1.0.1
    • addedInput schema / properties / contributions
      Added value: +{
      +  "default": false,
      +  "type": "boolean"
      +}
  3. Changed1 schema field changedv0.2.0
    • addedInput schema / properties / targets
      Added value: +{
      +  "anyOf": [
      +    {
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null
      +}
  4. First observedv0.1.0

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already disclose the non-read-only, non-idempotent, closed-world profile, and the description aligns with it by explaining that `start` creates a job on the `runs` resource rather than returning numbers directly. It also discloses what `result` produces (P5/P50/P95 per target driver by month, in its own unit) and the seed's determinism, but says nothing about error conditions or how long a start takes to become readable via status.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The action list and the guide pointer are front-loaded, which is good, but the middle sentence is an overloaded multi-clause run-on that nests four actions plus forecast semantics. The reST backticks add noise for an agent, and the forecast.json detail could be trimmed since an output schema exists.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter, multi-action tool with an output schema, the description covers the action semantics, the run-job model, currency/position sourcing, and the guide dependency. The remaining gap is operational: no indication of whether `start` is synchronous, how `status` conveys progress, or how `list` is scoped/paged.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so every parameter is already documented by the schema. The description adds only marginal meaning — that `base_currency` is the base of `positions` and that a portfolio supplies its own currency — and that point is already stated in the schema description, while fields like `contributions`, `draws`, and `id` get no extra interpretation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb set and resource upfront: 'Runs on the paths of a scenario' with actions start, status, result, list. The second sentence distinguishes each action's distinct effect (drawing paths, reporting a job, per-position results plus forecast, workspace-wide listing), so an agent can tell what it is and which mode it needs without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit precondition ('Read guide(name="run-report") first') and maps each action to its purpose, which effectively routes action selection. It does not explicitly differentiate from the sibling `jobs` tool or state when a run should be preferred over `scenario`/`portfolio` calls, so the comparison to alternatives is only implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.