Skip to main content
Glama

probe

Runs a record-only dry run to verify demo selectors and timing before rendering, then writes or compares a golden baseline for regression checks.

Instructions

Record-only dry run to verify selectors/timing (narration optional). With updateGolden, writes golden/probe.json (the regression baseline); with golden, deep-compares against it and returns match + field-level diffs. Returns a jobId immediately — poll job_status. Rejects if another job is running.

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": {
      "dir": "<dir>"
    },
    "name": "probe"
  }
}

Input Schema

NameRequiredDescriptionDefault
dirYesdemo project directory — pass an absolute path
freshNorun against a WIPED throwaway profile — use for any demo whose story starts at a first-run gate, onboarding, an empty state or a one-shot flow, since carried-over cookies/localStorage silently record the wrong story. Not for logged-in demos (a fresh profile has no login).
goldenNocompare against golden/probe.json; returns match + diffs (CI guard)
paramsNostoryboard template params (name → value); each must be declared in the storyboard's params block. Substitutes {{name}} across all stages.
captureNo
cookiesNocookies to seed before the first action (name, value, domain[, path, secure, httpOnly, sameSite, expires]). Also storyboard setup.cookies.
profileNoChrome user-data dir (logged-in profile)
headlessNorun Chrome headless (default false — headed, like the CLI)
fromSceneNoresume: keep the previous take's scenes before this scene id (footage + timeline, verified unchanged by hash) and record from it — after a late-scene failure or a change to the tail of the storyboard
storageStateNoabsolute path to a Playwright storageState JSON (cookies + per-origin localStorage) to seed into the profile before the first action — for cookie-gated sites. Also available as storyboard setup.storageState.
updateGoldenNowrite golden/probe.json from this probe (commit it as the baseline)
profileSeededNothe profile is seeded on purpose (login / cookie gate): silence the carried-over-state warning. Implied by storageState/cookies.

Output Schema

NameRequiredDescriptionDefault
kindYes
jobIdYes
statusYes
demoDirYesresolved absolute demo directory
logFileYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.20.2
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / properties / params / propertyNames
      Added value: +{
      +  "type": "string"
      +}
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
  2. Changed5 schema fields changedv0.14.1
    • addedInput schema / properties / cookies
      Added value: +{
      +  "description": "cookies to seed before the first action (name, value, domain[, path, secure, httpOnly, sameSite, expires]). Also storyboard setup.cookies.",
      +  "items": {
      +    "additionalProperties": false,
      +    "properties": {
      +      "domain": {
      +        "type": "string"
      +      },
      +      "expires": {
      +        "type": "number"
      +      },
      +      "httpOnly": {
      +        "type": "boolean"
      +      },
      +      "name": {
      +        "type": "string"
      +      },
      +      "path": {
      +        "type": "string"
      +      },
      +      "sameSite": {
      +        "enum": [
      +          "Strict",
      +          "Lax",
      +          "None"
      +        ],
      +        "type": "string"
      +      },
      +      "secure": {
      +        "type": "boolean"
      +      },
      +      "url": {
      +        "type": "string"
      +      },
      +      "value": {
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "name",
      +      "value"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • addedInput schema / properties / fresh
      Added value: +{
      +  "description": "run against a WIPED throwaway profile — use for any demo whose story starts at a first-run gate, onboarding, an empty state or a one-shot flow, since carried-over cookies/localStorage silently record the wrong story. Not for logged-in demos (a fresh profile has no login).",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / fromScene
      Added value: +{
      +  "description": "resume: keep the previous take's scenes before this scene id (footage + timeline, verified unchanged by hash) and record from it — after a late-scene failure or a change to the tail of the storyboard",
      +  "type": "string"
      +}
    • addedInput schema / properties / profileSeeded
      Added value: +{
      +  "description": "the profile is seeded on purpose (login / cookie gate): silence the carried-over-state warning. Implied by storageState/cookies.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / storageState
      Added value: +{
      +  "description": "absolute path to a Playwright storageState JSON (cookies + per-origin localStorage) to seed into the profile before the first action — for cookie-gated sites. Also available as storyboard setup.storageState.",
      +  "type": "string"
      +}
  3. First observedv0.9.0

TDQS

A3.8/5.0
Behavior3/5

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

With no annotations, the description carries the full burden and does well on lifecycle: it discloses that a jobId returns immediately, that job_status must be polled, and that the call is rejected while another job is running. It also explains the golden write-versus-compare side effects. It is silent on what happens to a pre-existing golden file on an updateGolden run and on any permission or environment prerequisites, which keeps it at a 3 rather than higher.

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?

Four sentences, front-loaded with purpose, then conditional golden behavior, then the job lifecycle. Dense but every clause carries information; only 'narration optional' floats without much anchoring to the schema.

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 12-parameter job-launching tool with an output schema and no annotations, the description covers the async execution model, the golden regression workflow, and the concurrency rejection rule. The remaining parameters (capture, fresh, headless, cookies, profile) are well documented in the schema at 92% coverage, so the description need not restate them.

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

Parameters4/5

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

Schema coverage is already 92%, so the baseline is 3, but the description adds real meaning the schema does not: the ordering and relationship between updateGolden (writes the baseline) and golden (deep-compares against it and returns field-level diffs), which are separate boolean properties with no stated interaction in the schema itself.

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 opens with a specific verb-and-resource framing: a record-only dry run that verifies selectors and timing, which clearly separates it from the actual recording siblings (record, render, walkthrough). It stops short of naming those siblings explicitly, so the agent must infer the boundary rather than being told.

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?

It gives a clear condition for the tool's primary use (verify selectors/timing before committing to footage) and spells out the two golden-related modes, including that golden acts as a CI guard. It does not state when to prefer this over record or when a dry run is unnecessary, so there is no explicit exclusion guidance.

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