Skip to main content
Glama

start_grab_session

Destructive

Starts a capability-keyed Raven grab bridge on loopback to proxy a local app, inject the grab overlay into HTML, and surface design and motion suggestions for the page.

Instructions

Start a capability-keyed Raven grab bridge on loopback. Proxy mode is the preferred zero-paste path: it serves a running local app with the overlay injected into HTML; the manual script tag remains available when needed. When proxying the designer's own local dev server, Grab's Motion tab finds motion for the page and builds playgrounds itself; pass profile and project when the project has a taste binding so those suggestions follow the designer's notes and earlier motion decisions.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "start_grab_session"
  }
}

Input Schema

NameRequiredDescriptionDefault
pathNoPath to DESIGN.md to expose over /tokens. Optional when proxy_target is set — a minimal temp DESIGN.md is created automatically. Required (and must exist) when proxy_target is omitted.
portNoOptional port; defaults to an ephemeral loopback port
roleNoOverlay role; consumer preserves the component-request flow, maintainer enables direct design-system component creationconsumer
profileNoTaste profile for the Motion tab's suggestions. Pass with project, or omit both.
projectNoBound project for the Motion tab's suggestions. Pass with profile, or omit both.
proxy_targetNoURL of a running local dev server; the bridge will serve that app with the grab overlay auto-injected into every HTML page — user opens the bridge URL, zero setup

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv3.0.0
    • addedInput schema / properties / profile
      Added value: +{
      +  "description": "Taste profile for the Motion tab's suggestions. Pass with project, or omit both.",
      +  "type": "string"
      +}
    • addedInput schema / properties / project
      Added value: +{
      +  "description": "Bound project for the Motion tab's suggestions. Pass with profile, or omit both.",
      +  "type": "string"
      +}
  2. First observedv2.2.9

TDQS

B3.3/5.0
Behavior2/5

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

Annotations declare destructiveHint=true and idempotentHint=false, but the description never explains what a new session replaces, what happens if one is already running, or what 'capability-keyed' means in practice. It describes proxy injection behavior, but the destructive and non-idempotent traits that matter most for an agent are left entirely unexplained.

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 mode guidance is front-loaded, which is good, but the second sentence is a long clause-chained run-on mixing Motion-tab behavior, playground construction, and taste-binding preconditions. It is dense and somewhat jargon-laden rather than crisp.

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?

There is no output schema, so the description should say what the caller gets back (bridge URL, port, capability key for the overlay). It covers proxy vs manual modes and the Motion tab but leaves the return behavior and session lifecycle implicit for a six-parameter session-start tool.

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 the schema already documents all six parameters, including the path/proxy_target interplay and the profile-with-project pairing. The description reinforces the profile/project coupling for Motion-tab suggestions but adds little syntactic or behavioral detail beyond the schema.

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 concrete verb and resource: it starts a grab bridge on loopback and serves a running local app with the overlay injected. 'Capability-keyed Raven grab bridge' is jargon, but the proxy-mode sentence makes the actual effect understandable and distinguishes it from stop_grab_session.

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 explicitly says proxy mode is the 'preferred zero-paste path' and that the manual script tag 'remains available when needed', which gives an agent a mode-selection rule. It also states profile/project should be passed together only when the project has a taste binding, though it never says when not to start a session at all (e.g., if one is already running).

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

Deploy Server

Other Tools