Skip to main content
Glama
Brilliant MCP

Brilliant MCP

Official

read

Read-onlyIdempotent

Inspect project canvases, films, and design systems by path, element ID, or filters; return blueprint, summary, or skeleton fences for editing and analysis.

Instructions

Read the project's documents, each answered as the fence you would send back through edit: a canvas as bl with file(path) first and its rows (ids bound), a film as bm, a design system as ```ds. A canvas answer lists the films that name it above its fence (films: Motion/Launch.bm). Pass paths (canvas paths such as "Projects/Dashboard", "Motion/Launch.bm", "Styles/default.ds"), ids (element ids or #refs, with their canvas in paths) and/or the filters (query, textContent, type, fillColor, componentName) to find elements across canvases. format is "blueprint" (default), "summary" (compact metadata) or "skeleton" (summary plus the tokenRefs, no geometry), the fence the carrier. (External MCP clients: call init first for usage docs. Hosted-CLI and sub-agents have docs pre-loaded.)

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": "read"
  }
}

Input Schema

NameRequiredDescriptionDefault
idsNoElement IDs (or #refs) to read, the same as listing them in `scope`. `elementIds` is accepted as an alias.
diskNotrue answers from the saved .bl files on a background isolate: it never loads, opens or writes a canvas, whatever its size, so a heavy or closed canvas is safe to read. Rows come as stored, one header per canvas names its row count and bytes, and a canvas open in the app says a change not saved yet is not here. Takes paths (omit to search every canvas), ids, the filters, depth, limit (rows, default 200) and the disk-only pattern, ancestors, subtree, consumersOf.
fullNoREAD-ONLY. When true (with format="blueprint"), return the COMPLETE vector geometry even for a large path. Default false: a vector whose blueprint would blow the per-readback token budget is summarized to node count + bounds + this flag as its continuation door (a one-line note names what was elided). Set true to inspect the full node/edge graph of one big vector; scope it to that element to keep the readback bounded.
typeNoFilter by element type. One of: vector, line, circle, rectangle, text, parent.
depthNoSubtree depth per match, in every format. 0 = matched element only, 1 = + immediate children, etc. Omitted: unlimited for "blueprint", the matched elements only for "summary" and "skeleton" (each record names its parentId).
limitNoMax top-level matches across all canvases. Defaults to 50. It applies with explicit element IDs too.
pathsNoThe documents to read: canvas paths (e.g. "Projects/Dashboard", .bl optional), films ("Motion/Launch.bm") and design systems ("Styles/default.ds"). Omit with a filter to search every canvas.
queryNoCase-insensitive substring match on element name AND canvas path. Element matches answer as fences; canvas matches ride the `canvases:` line. Canvas matching only runs when no `paths` are given. With a design system in `paths`, its statements whose token name contains it.
formatNoOutput shape per canvas, inside its fence. "blueprint" (default) is the rows with their ids, what edit takes back. "summary" is compact metadata (id, name, type, parentId, parentName, childCount, text snippet). "skeleton" adds the design-system tokenRefs and omits geometry.
patternNoWith disk: a regular expression over each stored row, for what the filters leave unnamed (a font size, a token, an override).
projectNoOptional: run THIS call against a project other than the session's bound one: a name or key from list_projects (or an unambiguous name/handle substring), or the absolute path of a project folder (one holding .bl files, or an empty one), which opens in the background and is added to list_projects. Unknown/ambiguous is refused with candidates.
subtreeNoWith disk: each matched row carries its descendants, bounded by depth.
ancestorsNoWith disk: each matched row carries its parent chain, board first.
fillColorNoFind elements with a fill matching this hex color (e.g. "#FFCC00" for yellow). Perceptual color matching, close shades are included.
sessionIdNoYour session id from init: #refs resolve per session.
consumersOfNoWith disk: the id of a component master. Answers each canvas holding a copy of it: the copies, and the canvas row count to weigh a master edit. Set a master's id, not a variant child, for the copies of that master.
textContentNoCase-insensitive substring match on text element content.
componentNameNoFind instances of a component whose master name contains this substring (case-insensitive).
expandInstancesNoREAD-ONLY. When true (with format="blueprint"), a component instance is not collapsed to its compact inst() line: its derived children are shown as full lines with their REAL ids so you can inspect and target them (via read/execute_commands). Those children are managed by the master and are read-only; a change to them is a change to override(...) on the instance. Default false (the compact inst() form). Bounded by `depth` like any subtree.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.10

TDQS

A3.6/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: the output is a round-trippable fence in a specific DSL dialect per document type, a canvas answer lists the films that reference it, and the chosen `format` determines which fence carrier is returned.

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?

Purpose is front-loaded and the length is defensible for 19 parameters, but sentences are packed with nested parentheticals and undefined domain terms, forcing the agent to decode vocabulary instead of deciding an action. Several clauses (the fence-type enumeration, the films-above-the-fence note) could be trimmed or moved to the `init` docs it already points to.

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 19-parameter tool with no output schema, the description does the necessary work: it explains the shape of what comes back (per-document fences, blueprint vs summary vs skeleton), how to scope a read, and where to get fuller docs via `init`. Gaps like pagination defaults and error/refusal behavior are covered in the schema rather than the prose.

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 description coverage is 100%, so every one of the 19 parameters is already documented, and the description largely restates that: it enumerates paths, ids, the same filter names and the same three format values. It adds some framing by tying `format` to the fence returned, but it does not meaningfully extend meaning beyond the schema for the majority of parameters.

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 uses a specific verb and resource — 'Read the project's documents' — and immediately frames the return value as 'the fence you would send back through edit', which distinguishes it from the write-side sibling. However, the heavy DSL jargon ('```bl', 'carrier', 'rows (ids bound)') makes the first read harder to parse than a plain statement of purpose would.

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?

It gives selection guidance — pass `paths`, `ids`, and/or filters to find elements across canvases — and states the prerequisite that external MCP clients must call `init` first. It stops short of saying when to prefer this over other read-ish siblings such as `get_selection`, `lookup`, or `objects_result`, and names no exclusions.

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