Skip to main content
Glama

run_experiment

Acquire a declared action with optional metric bounds to run a trial, returning ID, conditions, effective config, metrics, checks, and record path.

Instructions

Acquire one declared action, with optional metric bounds {name: {le: max, ge: min}}. Returns ID, conditions, effective config, metrics, checks and record path. A completed run can miss goals. Reuse a key for retries, use a new key for a fresh trial. Background runs survive client exit. Simulator-only pace delays acquisition by 0..600 seconds; fault='sample_gap' truncates a trace.

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": {
      "uri": "<uri>",
      "action": "<action>"
    },
    "name": "run_experiment"
  }
}

Input Schema

NameRequiredDescriptionDefault
keyNo
uriYes
noteNo
paceNo
faultNo
goalsNo
actionYes
backgroundNo
conditionsNo
constraintsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.6/5.0
Behavior4/5

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

With no annotations, the description carries the behavioral burden and does meaningful work: it discloses that a completed run can miss its goals, that background runs persist after client exit, that simulator pace adds 0..600s of delay, and that fault='sample_gap' truncates a trace. It still omits error/failure behavior, whether the call blocks until completion, and any permission or irreversibility notes for what is clearly a mutating operation.

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

Conciseness4/5

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

Sentences are dense but each carries distinct information: purpose and return shape first, then the goal-miss caveat, then key semantics, then background and simulator-only caveats. The jargon-heavy opening ('Acquire one declared action') is slightly cryptic and could be plainer, but there is no filler.

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

Completeness3/5

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

For a 10-parameter mutating tool with no annotations, no output schema and no schema descriptions, the definition covers return contents and several behavioral caveats but leaves core inputs (uri, action, conditions, constraints) and error/blocking behavior undocumented. It is adequate to attempt a call but not complete enough to call confidently.

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 description coverage is 0% across 10 parameters, so the description must compensate; it explains key (retry identity), goals (metric bounds shape {le, ge}), background, pace (0..600s simulator delay) and fault ('sample_gap'). The two required parameters, uri and action, plus note, conditions and constraints are left unexplained, so the compensation is roughly half-complete.

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

Purpose4/5

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

The description states a specific resource and operation ('Acquire one declared action', returning ID, conditions, effective config, metrics, checks and record path), so an agent can tell this is the run-execution/creation tool rather than a lookup like get_run or list_runs. The verb 'acquire' is idiosyncratic, but the enumerated return payload makes the purpose unambiguous.

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

Usage Guidelines3/5

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

It gives useful within-tool usage rules: 'Reuse a key for retries, use a new key for a fresh trial' and 'Background runs survive client exit' tell the agent how to pick values. However it never says when to prefer this over siblings such as cancel_run, get_run, or compare, nor does it state prerequisites or exclusions.

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