Skip to main content
Glama
Brilliant MCP

Brilliant MCP

Official

edit

Destructive

Apply ordered fence edits to project documents, canvases, design systems, and films, returning changed elements, refs, diagnostics, and preview screenshots.

Instructions

Edit the project's documents. text holds one or more fences, applied in order: bl (a canvas, blueprint rows: omit ids for new elements, lead with an id or #ref to modify, delete(#ref) to remove, preview(#a, #b) as a row for a screenshot), html (a canvas, HTML with inline CSS converted to elements), ds (a design system, statements spliced), bm (a film, the whole document replaced). The first row of every fence is file(path): file("Projects/Launch"), file("Styles/default.ds"), file("Motion/Launch.bm"). A call holds fences on any number of documents, canvases included, applied in order, one result entry per fence; a #ref and a // label checkpoint belong to the canvas of their fence. A bl fence's rows apply as they go and the first bad row halts with one line. The answer is the block result: the canvas fact, what changed, the refs, the diagnostics, the notes and a screenshot of the preview row. Pass your sessionId from init. (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": "edit"
  }
}

Input Schema

NameRequiredDescriptionDefault
textNoThe fences: ```<bl|bm|ds|html> on its own line, file(path) as the first row, the rows, ``` on its own line. Several fences in one text apply in order.
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.
textFileNoInstead of text: the absolute path of a local file holding the fences, for a block a script generated. Same pipeline and same answer as text, plus a `job:` line. With no requestId the id is a hash of the bytes, so resending the same file after a timeout converges on the first answer; a file whose bytes changed is a new request. Desktop only.
requestIdNoOptional idempotency key. Pass a stable, unique id for this logical request and REUSE the SAME id if you retry after a timeout or relay error: the retry converges on the original result instead of applying a second time. The id is one request: for 2 minutes after a success, a call reusing it with the same text answers the first result, and with different text is refused with nothing applied, so new text takes a new id.
sessionIdNoYour session id from init (refs and design-system state are per session).
backgroundNoOptional. true answers a `job:` id at once and runs the call on; wait({job}) blocks until it ends and answers its result. An edit waits its turn behind other agents' writes instead of refusing. Use it for a call that may outlast your client's timeout.
designSystemNoOptional. Design-system mode for this and all later calls (sticky, once set it persists until changed). One of: `"default"` (use the project default DS, token discipline enforced, no bare hex/numerics on tokenizable slots); `"new"` (author your own DS, write a ```ds fence before any bl rows); `"none"` (sovereign, bare hex/numeric values allowed); or the name of a brand YOU authored earlier this session. Omit to keep the current mode (external sessions default to `"none"`).
response_modeNoOptional. "full" (default) answers the block result with the blueprint of every affected element, or a read handle when that blueprint runs past 50 rows. "compact" answers the block result with a read handle instead of the blueprint, names up to 6 changed elements (past 6, 5 and a count), and keeps every warning, error and new ref.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.10

TDQS

A3.7/5.0
Behavior4/5

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

Annotations already flag destructiveHint=true and readOnlyHint=false, but the description adds material behavior the annotations cannot convey: bl rows apply incrementally with the first bad row halting, bm replaces the whole document, ds splices statements, and one call can span multiple documents. The requestId convergence rule (same id + same text returns the first result, different text is refused with nothing applied) is exactly the kind of retry-safety detail an agent needs. It stops short of saying whether a halted bl fence leaves the already-applied rows committed.

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 and fence types are front-loaded, but the prose is a dense run-on with nested parentheticals and unlabeled jargon (#ref, checkpoint, canvas fact) that slows parsing. Little is truly redundant, yet the sentences are packed to the point of obscuring the call order of operations.

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 an 8-parameter tool with no output schema, the description covers the response shape (canvas fact, changes, refs, diagnostics, notes, preview screenshot) and the interaction between text, project scoping, background and requestId. It omits failure modes beyond bl row halting and any permission or concurrency refusal conditions.

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 100%, so the baseline is 3, but the description earns more: it explains the file(path) first-row convention for every fence, that textFile has the same pipeline as text plus a hash-based id, that background waits its turn behind other agents' writes, and that designSystem is sticky across later calls. These are operational semantics not present in the schema strings.

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?

"Edit the project's documents" gives a specific verb and resource, and the fence taxonomy (```bl, ```html, ```ds, ```bm) makes the tool's model of operation concrete. It does not, however, contrast itself with siblings like create_html, convert_html or execute_commands, so an agent must infer the boundary from names alone.

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 context is implied rather than stated: it tells you to call init first, to pass sessionId, and to use background for calls that may outlast a client timeout, but never says when this tool is the right choice over a sibling or when it is not. The when-to-use signal is embedded in fence semantics rather than spelled out.

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