Skip to main content
Glama

Drawbridge Network Diagrams

edit_diagram

CHANGE AN EXISTING DIAGRAM instead of regenerating it: add, update and remove devices and links in a .drawio document and get the edited document back. This is the tool for "add a switch to this drawing" — create_diagram would redraw the whole page and throw away every position a human placed by hand. Call describe first to get the ids, then name them here. Everything you do not name keeps its exact position. Do NOT set x/y on a new device: Drawbridge places what you add below the existing drawing, which is the whole point of using this rather than editing the XML. Say what a new device belongs UNDER with near, naming a device already in the drawing: it lands straight below that one, in free space, so use it on every device you are about to cable to something. Put cables in an aggregate with bundle on add_edge or update_edge — its name, "ae1": cables given one name share one ring, and a ring of that name already drawn is joined. A cable already in another ring is added to this one; to move it, send bundle "" first and then the new name, in the same call. Set kind on every device you add or it draws as a plain box, and read the notes in the result — a mistyped id skips that one op and says so rather than failing the batch. The result names the ids it minted, in op order. Every id in an op must already exist when you send it — an op cannot name something an earlier op in the same call created, so adding a device and cabling it is two calls: add it, read the ids, then wire them. It writes nothing: save the returned document yourself, as it is — a cable or a position you write into the XML by hand skips the routing and the checks this tool makes. Results carry name: a suggested basename for this diagram. Write every file for one diagram into its own directory named after it — /.drawio, /.svg, /.cables.csv — so two diagrams never share a directory.

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": {
      "document": "<document>",
      "ops": "<ops>"
    },
    "name": "edit_diagram"
  }
}

Input Schema

NameRequiredDescriptionDefault
opsYesThe changes to apply, in order. Send a whole thought at a time rather than an op per call.
kindNoOutput format for the edited document. Defaults to drawio, which is what you want: it is the file the user keeps working on.
nameNoBasename to use for this diagram instead of the one derived from its content. Slugified; wins over the document’s own name.
themeNoRender theme. Omit to follow the OS appearance; pin it for machine-independent output.
documentYesThe .drawio document as XML text.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.8/5.0
Behavior5/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: it states the tool writes nothing and the caller must save the returned document, that a mistyped id skips one op rather than failing the batch, and that invalid cables/modules are refused and reported in `notes`. It also discloses results carry minted ids in op order plus a suggested basename.

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

Conciseness4/5

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

Front-loads purpose and the sibling distinction, then layers operational caveats in a logical sequence. Nearly every sentence carries a rule an agent needs, but the density of asides (file-naming convention, ring semantics restated from the schema) makes it longer than strictly necessary.

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 complex batch-mutation tool with a deeply nested ops schema and no output schema, the description covers the return shape (minted ids, `notes`, suggested `name`) and the surrounding workflow (describe → edit → save files per-diagram directory). Nothing an agent needs to invoke it correctly appears absent.

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 schema already documents most fields (including a long `bundle` entry). The description nonetheless adds strategic meaning: omit x/y because Drawbridge auto-places, use `near` on every device about to be cabled, `bundle` names a shared ring and moving a cable needs bundle "" then the new name in one call, and `kind` is mandatory or the device draws as a plain box.

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?

Opens with a specific verb and resource in caps — 'CHANGE AN EXISTING DIAGRAM' — and enumerates the operations (add, update, remove devices and links) plus the artifact type (.drawio). It immediately names the sibling it is not (`create_diagram`) and explains the difference in outcome, so an agent can discriminate without opening either schema.

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?

Gives explicit when-to-use routing: use this for 'add a switch to this drawing' because `create_diagram` would discard manual placement, and call `describe` first for ids. It also supplies concrete when-not rules — do NOT set x/y, do not hand-edit XML, and the two-call constraint for adding then cabling a device.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources