Skip to main content
Glama

Scaffold a new demo

init_demo

Scaffold a demo folder with a starter brief and storyboard; optionally inspect a live page URL to draft scenes and potential interaction steps for narration and click setup.

Instructions

Create demos// with a starter brief + storyboard. dir is the repo to scaffold into (absolute path recommended; default: server cwd). With fromUrl the page is inspected first (no LLM): its headings become scenes and its unique selectors become the beats + a _candidates list — you then write the narration and turn the candidate hover into the real click.

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

Input Schema

NameRequiredDescriptionDefault
dirNo
nameYesdemo name (creates demos/<name>/)
forceNo
fromUrlNodraft the storyboard from this live page
profileNofromUrl: Chrome user-data dir (logged-in pages)
headlessNofromUrl: run Chrome headless (default true)
viewportNofromUrl: viewport (default 1280x720)

Output Schema

NameRequiredDescriptionDefault
demoDirYes
briefPathYes
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. Changed4 schema fields changedv0.14.1
    • addedInput schema / properties / fromUrl
      Added value: +{
      +  "description": "draft the storyboard from this live page",
      +  "type": "string"
      +}
    • addedInput schema / properties / headless
      Added value: +{
      +  "description": "fromUrl: run Chrome headless (default true)",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / profile
      Added value: +{
      +  "description": "fromUrl: Chrome user-data dir (logged-in pages)",
      +  "type": "string"
      +}
    • addedInput schema / properties / viewport
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "fromUrl: viewport (default 1280x720)",
      +  "properties": {
      +    "height": {
      +      "type": "number"
      +    },
      +    "width": {
      +      "type": "number"
      +    }
      +  },
      +  "required": [
      +    "width",
      +    "height"
      +  ],
      +  "type": "object"
      +}
  3. First observedv0.9.0

TDQS

A3.7/5.0
Behavior4/5

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

With no annotations at all, the description carries the full burden and does a good job on the risky part: it discloses that fromUrl runs a non-LLM page inspection, that headings map to scenes and unique selectors to beats, and that a `_candidates` list is emitted for the agent to refine. It also discloses the default scaffold location ('server cwd'). The gap is the mutation profile: 'force' is never explained, so the agent cannot tell whether re-running overwrites existing demo files or errors out.

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?

Three sentences, front-loaded with the artifact created and then the two branches of behavior; nothing is padding. The final sentence is a heavy em-dash run-on that takes a second pass to parse, which is the only structural weakness.

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?

An output schema exists, so return values need not be described, and the fromUrl branch is unusually well covered for a tool with no annotations. However, a scaffolding tool with an unexplained boolean `force` and no statement about overwrite/collision behavior is missing the piece an agent most needs before calling it twice.

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 71%, and the description pushes past the schema where it matters: `dir` gains 'repo to scaffold into (absolute path recommended; default: server cwd)', and `fromUrl` gains the whole inspection pipeline and resulting storyboard shape. `profile`, `headless` and `viewport` are described in the schema as fromUrl-only, so that linkage is covered, but `force` receives no meaning in either place.

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 first sentence gives a concrete verb and resource: 'Create demos/<name>/ with a starter brief + storyboard', which tells an agent exactly what artifact appears on disk. It does not name or contrast a sibling (e.g. probe, inspect, get_storyboard_schema), so the differentiation work is left implicit, but the purpose itself is 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?

Usage is implied rather than stated: the description explains the fromUrl branch (page inspected first, no LLM) and the follow-up work the agent must do ('you then write the narration and turn the candidate hover into the real click'). It never says when to prefer this over probe or get_authoring_guide, nor when a plain scaffold without fromUrl is appropriate, and never warns about re-running into an existing directory.

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