Skip to main content
Glama
imgly

CoDesign

Official
by imgly
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Local

edit

Run JavaScript against the live CreativeEngine to change a design, then commit the result as a new revision. Requires a parent revision ID.

Instructions

Edit the CE.SDK canvas by running JavaScript against the live CreativeEngine, then commit the result as a new revision.

⚠ Call skill({ name: 'handbook' }) BEFORE your first edit. It documents the design loop, the typeface schema, and the engine recipes; on cryptic errors, query its quirks.md.

REQUIRED: parent is a revision id (returned by a previous edit), or the JSON null literal (no quotes) to start a new design. Omitting it is an error — there is no implicit 'continue from wherever'. In a fresh conversation, a request for a new design means parent: null — never resume a workspace design the user didn't reference.

Returns: the first content part is JSON { revision, parent, names? } — store revision so you can pass it as parent on the next edit. names lists every named block in the committed scene: those are exactly the strings engine.design.findByName(name) resolves in your NEXT edit, so name what you build and re-find it instead of matching copy. When the edit changed the scene, the result also ends with a downscaled render of the (first) changed page — verify your work from it instead of spending a preview call. preview remains required for full-size judging (the judge loop) and multi-page review; set render: false to skip the image on read-only/diagnostic edits.

code return contract (STRICT): return undefined (no message back), { type: "text", text }, { type: "image", data: "<base64>", mimeType }, or an array of those. Anything else (raw strings, Blobs, plain objects) is rejected.

DIALECT (enforced): mutations go through engine.design (create/build/setProps/…). Code that mutates via engine.block.* is rejected before execution with the equivalent calls; // engine.block: <reason> opts out for calls the facade lacks.

code scope: engine (with engine.design), plus findText(copy) / findAllText(copy) for reaching a block by its text. Use them instead of comparing text strings with === — the copy on the page routinely carries a trailing space or an NBSP (before a €/%), which is what makes hand-rolled lookups throw. Matching folds those space variants and trims; a miss lists the copy actually on the page.

Dirty-on-throw: if your code throws, the engine slot is marked dirty and the next edit pays one engine reload (regardless of parent). Do not catch-and-swallow errors that should propagate — let them throw so this safety contract kicks in.

Optional: title (set on parent=null only — the design's display name) and note (a one-liner describing what this edit accomplished — purely descriptive, helps you re-ground after a rewind).

Refused parents: if the user saved changes in the browser editor between your parent and the design head, this edit would discard them, so it is rejected — call changes to see what they did and which revision to build on.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
codeYesAsync JS body. `engine` is in scope, plus `engine.design` — the preferred nested-props facade; EVERY member returns a Promise (await it): create({ type, name?, props?, children? }, { parent? }), setProps(id, props), getProps(id, select?) — see the api skill. Strict return contract per the handbook.
forkNoSet true ONLY when the user explicitly asked to discard their own browser-editor changes and branch from an older revision. Without it, `edit` refuses a parent whose path to the head contains a save the user made in the editor.
noteNoFreeform descriptive text — what this edit accomplished. Metadata only; never load-bearing.
titleNoDisplay name for the design. Set only when parent=null (creating a new design). For mid-chain renames use the `rename` tool.
parentYesParent revision id from a previous edit (a string). To start a new design root, use the JSON null literal. REQUIRED — there is no implicit default.
renderNoDefault true: a mutating edit's result ends with a downscaled render of the (first) changed page. Set false to skip the image on read-only or diagnostic edits where seeing the canvas adds nothing.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A5/5.0
Behavior5/5

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

With no annotations provided, the description carries the full behavioral burden and does so thoroughly. It discloses the revision-commit side effect, the exact return JSON shape, the strict `code` return contract, the engine.design dialect enforcement, the dirty-on-throw engine reload consequence, and the refusal behavior when the user saved changes in the browser editor.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every sentence carries operational value, and it is well structured with bolded labels. Critical constraints like the handbook prerequisite, required `parent`, and return contract are front-loaded, while optional parameters and edge cases are grouped at the end.

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?

Given no output schema and no annotations, the description fully compensates by specifying return values, failure modes, parameter constraints, and relationships to sibling tools. The agent has everything needed to call `edit` correctly and recover from common errors such as refused parents or thrown code.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 100%, the description adds substantial meaning beyond the schema: `parent` has no implicit default and must be the JSON null literal for new designs, `code` has a strict return contract and scope rules, `title` only applies when parent=null, `note` is purely metadata, and `render` should be disabled only for read-only or diagnostic edits.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence states a specific verb and resource: 'Edit the CE.SDK canvas by running JavaScript against the live CreativeEngine, then commit the result as a new revision.' It clearly differentiates this mutation-and-commit tool from siblings like `preview`, `changes`, and `rename` by defining the edit lifecycle.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance: call `skill({ name: 'handbook' })` before first use, use the returned render instead of `preview` for quick verification, keep `preview` for full-size/multi-page judging, and call `changes` when a parent revision is refused. It also notes that `rename` should be used for mid-chain renames, not `title`.

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