Skip to main content
Glama
the-real-talk

the-real-talk

bind_variable_batch

Batch-bind multiple fields to variables across all matching nodes under a root node in one call. Filter by type, name, or variant and preview eligible nodes with a dry run.

Instructions

Bind several fields to variables on ALL nodes selected under rootId, in one call. select (at least one criterion, all must match): type (FRAME, TEXT, COMPONENT, INSTANCE...), nameEquals, nameMatches (regular expression), variantProperties ({"Size":"Compact"}, on COMPONENT or INSTANCE). bindings: [{field, variableId}] with the fields of bind_variable_field plus fills and strokes (binds the color of every SOLID paint; COLOR variable); variableId null unbinds. Instance children are skipped unless includeInstanceChildren. where (optional) keeps a binding only where a field meets a condition: {field?, rawValue?, unbound?, boundTo?}. field is the field read (default: the binding's own field, so {unbound:true, rawValue:12} on a paddingTop binding binds only raw paddingTop values equal to 12); rawValue is a number, string or boolean (a #rrggbb text for fills and strokes); unbound:true needs no variable on that field; boundTo: needs that variable already bound. For fills and strokes the condition is per paint. matched counts the nodes selected, eligible those where at least one binding passes where. dryRun:true lists the eligible nodes (matchedIds, max 500) and fieldsWouldBind, and writes nothing: use it first. Returns matched, nodesBound, nodesFailed, fieldsBound and failures [{nodeId, name, field, error}] (200 at most, failuresTotal gives the real count). Time budget: if reached, the answer is PARTIAL with nextCursor; counts are per call, add them up.

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": {
      "rootId": "<rootId>",
      "select": "<select>",
      "bindings": "<bindings>"
    },
    "name": "bind_variable_batch"
  }
}

Input Schema

NameRequiredDescriptionDefault
whereNo
cursorNonextCursor of a previous PARTIAL answer, to continue where it stopped
dryRunNo
rootIdYesNode under which the nodes are selected (the root itself is a candidate)
selectYes
bindingsYes
maxNodesNoMatched nodes per call (default 5000)
timeBudgetMsNoTime budget of the plugin for this call in ms (default 60000, max 100000). When it is reached the answer says it is PARTIAL and gives nextCursor.
includeInstanceChildrenNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.0.0

TDQS

A4/5.0
Behavior4/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 so well: dryRun writes nothing, variableId null unbinds, where filters per binding, failures are capped at 200 with failuresTotal, and a time-budget cutoff yields PARTIAL with nextCursor and per-call counts. Missing are permission requirements and whether rebinding is reversible, which matter for a mutation tool.

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 first sentence is well front-loaded, but the body is a dense run-on with deep parentheticals (nested where/rawValue explanation mid-sentence) that is hard to parse on first read. The information is mostly high-value rather than filler, so the cost is presentation, not waste.

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

Completeness5/5

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

For a 9-parameter nested mutation tool with no output schema, the description covers selection, binding, conditional filtering, dry-run, pagination, failure reporting and partial-result accounting. An agent could invoke it correctly and interpret its response from this text 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 only 44%, so the description must compensate and largely does: it expands select criteria, bindings item shape, the fills/strokes extension and COLOR variables, and the where object including the default that field reads the binding's own field and the #rrggbb rawValue format. The top-level maxNodes and timeBudgetMs parameters are only explained in the schema, which is acceptable given their schema descriptions.

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 opening sentence gives a specific verb, resource and scope: bind several fields to variables across ALL nodes under rootId in one call, which implicitly separates it from the single-field bind_variable_field. It never names a sibling as an alternative to use instead, so differentiation is conveyed by scope wording rather than explicit routing.

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 concrete procedural guidance: run with dryRun:true first to see eligible nodes and fieldsWouldBind, and instance children are skipped unless includeInstanceChildren is set. It stops short of stating when to prefer bind_variable_field or bind_variable over this batch form.

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