Skip to main content
Glama

Draft a storyboard from a Playwright trace or test

import_trace

Converts a Playwright trace.zip or *.spec.ts test into a demos// storyboard scaffold, using recorded actions and selectors as scenes and leaving narration placeholders for completion.

Instructions

Turn a Playwright trace.zip (context.tracing / --trace on) or a *.spec.ts test file into demos// with a draft storyboard: the run's own actions and selectors become scenes (cut at navigations and async payoffs), narration is left as placeholders, and _notes lists what was approximated. No LLM, no browser. Then write the narration and probe.

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": {
      "file": "<file>",
      "name": "<name>"
    },
    "name": "import_trace"
  }
}

Input Schema

NameRequiredDescriptionDefault
dirNorepo to scaffold into (default: server cwd)
fileYesabsolute path to trace.zip or the test file
nameYesdemo name (creates demos/<name>/)
forceNo

Output Schema

NameRequiredDescriptionDefault
notesYes
stepsYes
scenesYes
demoDirYes
storyboardPathYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 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"
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
  2. Addedv0.14.1

TDQS

A4.1/5.0
Behavior3/5

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

With no annotations, the description does real work by disclosing 'No LLM, no browser', that narration is left as placeholders, and that _notes records what was approximated. However, it never says what happens if demos/<name> already exists or what the force flag overrides — the key mutation risk for a scaffolding tool — so the destructive/overwrite profile is left implicit.

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?

The core capability, output location, and post-step are front-loaded in two sentences with no filler. The parenthetical clause is dense but each element (cut points, placeholder narration, _notes) conveys real behavior.

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?

An output schema exists, so return values needn't be explained, and the description covers inputs, generated file layout, and the intended next action. The remaining gap is the overwrite/force behavior for a tool that writes into the repo, which an agent must currently infer from the schema alone.

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 75% and the only undocumented parameter is `force`, so the baseline is already high. The description adds meaning beyond the schema for `file` (accepts trace.zip from context.tracing/`--trace on` or a *.spec.ts) and confirms `name` produces demos/<name>/, which helps an agent pick the right input format.

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 and resource — converting a Playwright trace.zip or *.spec.ts into demos/<name>/ with a draft storyboard — and describes the produced artifact in concrete terms (scenes cut at navigations and async payoffs, placeholder narration, _notes). This clearly separates it from siblings like init_demo (empty scaffold) and probe (narration work).

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 names the valid inputs (context.tracing / `--trace on` trace.zip, or a test file) and points to the follow-up step: 'Then write the narration and probe.' What's missing is explicit routing versus init_demo or record — i.e., when to use this instead of starting a demo by hand or recording a fresh session.

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