mcp

Datadef's standard for what makes a diagram readable, size, edge discipline, nested zones, annotations, and the tool order for building or editing. Read this BEFORE your first canvas_* call. It is the same standard Datadef's own generator follows, so a diagram you build by hand comes out indistinguishable from a generated one.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Get an overview of the current canvas: every node with its id, type, label and group, plus all connections and groups. Call this first, before any edit, so you work from real node ids instead of guesses. Operates on one Datadef diagram, named by diagram_id. If you have not already, call get_design_guide first: it carries Datadef's size, edge, and zone standard, and diagrams built without it read poorly.

{
  "type": "object",
  "properties": {
    "diagram_id": {
      "type": "string",
      "description": "Canvas id, from list_diagrams, create_diagram, or create_blank_diagram."
    },
    "includeColumns": {
      "type": "boolean",
      "description": "Include a short column list for each table node. Default false."
    }
  },
  "required": [
    "diagram_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Get full detail for specific nodes: all columns with types and keys, metadata, schedule, formula, owners. Use before modifying a node so you preserve fields you are not changing. Operates on one Datadef diagram, named by diagram_id.

{
  "type": "object",
  "properties": {
    "diagram_id": {
      "type": "string",
      "description": "Canvas id, from list_diagrams, create_diagram, or create_blank_diagram."
    },
    "nodes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "maxItems": 10,
      "description": "Node ids or exact labels. Up to 10 at a time."
    }
  },
  "required": [
    "diagram_id",
    "nodes"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Get exact geometry: every node's position and size in canvas units, the overall canvas bounds, and any nodes that overlap each other. Call this before moving, resizing, or placing anything precisely — positions are meaningless without it. Operates on one Datadef diagram, named by diagram_id.

{
  "type": "object",
  "properties": {
    "diagram_id": {
      "type": "string",
      "description": "Canvas id, from list_diagrams, create_diagram, or create_blank_diagram."
    },
    "nodes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Limit to specific node ids or labels. Omit to measure everything."
    }
  },
  "required": [
    "diagram_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Report where this canvas could be collapsed — groups of similar nodes that could become one summary node — without changing anything. Use it to decide whether the diagram is denser than it needs to be. Density is not automatically a problem: keep the detail when the detail is the point. Operates on one Datadef diagram, named by diagram_id.

{
  "type": "object",
  "properties": {
    "diagram_id": {
      "type": "string",
      "description": "Canvas id, from list_diagrams, create_diagram, or create_blank_diagram."
    },
    "minGroupSize": {
      "type": "integer",
      "minimum": 2,
      "maximum": 20,
      "description": "Smallest group worth reporting. Default 3."
    }
  },
  "required": [
    "diagram_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Search Datadef's icon library (2000+ cloud and data-tool logos) for a valid icon id. Use it when you want a specific vendor logo and are unsure of its exact id — passing an invalid id silently falls back to a generic icon. Operates on one Datadef diagram, named by diagram_id.

{
  "type": "object",
  "properties": {
    "diagram_id": {
      "type": "string",
      "description": "Canvas id, from list_diagrams, create_diagram, or create_blank_diagram."
    },
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "Tool or service name, e.g. \"snowflake\", \"kinesis\", \"power bi\"."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20,
      "description": "Max results, default 8."
    }
  },
  "required": [
    "diagram_id",
    "query"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Add one or more nodes to the canvas. Batch every node you want in a single call. Positions are assigned by canvas_layout_canvas afterwards — never set them yourself. Operates on one Datadef diagram, named by diagram_id. If you have not already, call get_design_guide first: it carries Datadef's size, edge, and zone standard, and diagrams built without it read poorly.

{
  "type": "object",
  "properties": {
    "diagram_id": {
      "type": "string",
      "description": "Canvas id, from list_diagrams, create_diagram, or create_blank_diagram."
    },
    "nodes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "table",
              "kpi",
              "dataSource",
              "pipeline",
              "consumption",
              "serviceIcon"
            ],
            "description": "table = a dataset with columns; dataSource = an external system feeding data in; pipeline = a job that moves or transforms data; consumption = a dashboard, app, or ML model reading data; kpi = a business metric; serviceIcon = a plain labelled service logo."
          },
          "label": {
            "type": "string",
            "description": "Display name. Use the real object name, e.g. \"fct_orders\"."
          },
          "description": {
            "type": "string",
            "description": "One line on what this is and why it exists."
          },
          "icon": {
            "type": "string",
            "description": "Icon id from search_icons, e.g. \"snowflake\". Omit if unsure."
          },
          "columns": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Column name, e.g. \"customer_id\"."
                },
                "type": {
                  "type": "string",
                  "description": "SQL type, e.g. \"varchar\", \"bigint\", \"timestamp\". Default \"unknown\"."
                },
                "isPrimaryKey": {
                  "type": "boolean"
                },
                "isForeignKey": {
                  "type": "boolean"
                },
                "description": {
                  "type": "string",
                  "description": "What the column means in business terms."
                }
              },
              "required": [
                "name"
              ],
              "additionalProperties": false
            },
            "description": "Columns. Table nodes only."
          },
          "pipelineType": {
            "type": "string",
            "description": "etl, elt, transformation, streaming, batch, cdc, or reverse_etl."
          },
          "schedule": {
            "type": "string",
            "description": "Cron expression or cadence, e.g. \"0 2 * * *\"."
          },
          "technology": {
            "type": "string",
            "description": "Implementing tool, e.g. \"dbt\", \"Airflow\"."
          },
          "kpiFormula": {
            "type": "string"
          },
          "kpiUnit": {
            "type": "string"
          },
          "kpiTarget": {
            "type": "string"
          },
          "dataOwner": {
            "type": "string"
          },
          "dataSteward": {
            "type": "string"
          },
          "teamInCharge": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "family": {
            "type": "string",
            "enum": [
              "source",
              "ingest",
              "bronze",
              "silver",
              "gold",
              "consume",
              "dbt",
              "neutral"
            ],
            "description": "Accent hue for the node tile: source=teal, ingest=blue, bronze/silver/gold=medallion layers, consume=magenta, dbt=coral. Tables infer their layer from names; set this for operators/endpoints or to override."
          },
          "group": {
            "type": "string",
            "description": "Group id or label to place this node in. The group must already exist."
          }
        },
        "required": [
          "type",
          "label"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 40
    }
  },
  "required": [
    "diagram_id",
    "nodes"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Add a single data node at an exact position, without connecting it to anything. Use when the user wants something placed somewhere specific, or when you will wire it up yourself afterwards. For building out a connected diagram, canvas_add_nodes is better — it batches and lets layout position everything. Operates on one Datadef diagram, named by diagram_id.

{
  "type": "object",
  "properties": {
    "diagram_id": {
      "type": "string",
      "description": "Canvas id, from list_diagrams, create_diagram, or create_blank_diagram."
    },
    "type": {
      "type": "string",
      "enum": [
        "table",
        "kpi",
        "dataSource",
        "pipeline",
        "consumption",
        "serviceIcon"
      ]
    },
    "label": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "icon": {
      "type": "string",
      "description": "Icon id from search_icons."
    },
    "technology": {
      "type": "string"
    },
    "x": {
      "type": "number",
      "description": "Absolute x. Omit to place clear of the existing diagram."
    },
    "y": {
      "type": "number",
      "description": "Absolute y."
    }
  },
  "required": [
    "diagram_id",
    "type",
    "label"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Change properties of existing nodes. Only the fields you pass are touched; everything else is preserved. To replace a table's columns use canvas_set_columns instead. Operates on one Datadef diagram, named by diagram_id.

{
  "type": "object",
  "properties": {
    "diagram_id": {
      "type": "string",
      "description": "Canvas id, from list_diagrams, create_diagram, or create_blank_diagram."
    },
    "updates": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "node": {
            "type": "string",
            "description": "Node id or exact label."
          },
          "label": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "icon": {
            "type": "string",
            "description": "Icon id from search_icons."
          },
          "pipelineType": {
            "type": "string"
          },
          "schedule": {
            "type": "string"
          },
          "technology": {
            "type": "string"
          },
          "kpiFormula": {
            "type": "string"
          },
          "kpiUnit": {
            "type": "string"
          },
          "kpiTarget": {
            "type": "string"
          },
          "dataOwner": {
            "type": "string"
          },
          "dataSteward": {
            "type": "string"
          },
          "teamInCharge": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "node"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 40
    }
  },
  "required": [
    "diagram_id",
    "updates"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Swap a node for a different one while keeping every connection, its position, and its group. Use this when a component changes — Redshift becomes Snowflake, a batch job becomes streaming — instead of deleting and rebuilding, which would lose all the edges. Operates on one Datadef diagram, named by diagram_id.

{
  "type": "object",
  "properties": {
    "diagram_id": {
      "type": "string",
      "description": "Canvas id, from list_diagrams, create_diagram, or create_blank_diagram."
    },
    "node": {
      "type": "string",
      "description": "Node id or exact label to replace."
    },
    "type": {
      "type": "string",
      "enum": [
        "table",
        "kpi",
        "dataSource",
        "pipeline",
        "consumption",
        "serviceIcon"
      ],
      "description": "New type. Omit to keep the current type."
    },
    "label": {
      "type": "string",
      "description": "New label."
    },
    "description": {
      "type": "string"
    },
    "icon": {
      "type": "string",
      "description": "Icon id from search_icons."
    },
    "technology": {
      "type": "string"
    },
    "keepColumns": {
      "type": "boolean",
      "description": "Carry the existing columns over to the replacement. Default true."
    }
  },
  "required": [
    "diagram_id",
    "node",
    "label"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Delete nodes and every edge touching them. Deleting a group also deletes the nodes inside it — check with canvas_describe_canvas first if that is not what you want. Operates on one Datadef diagram, named by diagram_id.

{
  "type": "object",
  "properties": {
    "diagram_id": {
      "type": "string",
      "description": "Canvas id, from list_diagrams, create_diagram, or create_blank_diagram."
    },
    "nodes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "description": "Node ids or exact labels."
    }
  },
  "required": [
    "diagram_id",
    "nodes"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Draw edges between nodes to show how data flows. Always label the edge with what actually happens ("ingest", "dbt transform", "hourly sync") — unlabelled edges make a diagram useless. Operates on one Datadef diagram, named by diagram_id.

{
  "type": "object",
  "properties": {
    "diagram_id": {
      "type": "string",
      "description": "Canvas id, from list_diagrams, create_diagram, or create_blank_diagram."
    },
    "edges": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "source": {
            "type": "string",
            "description": "Upstream node id or label — data flows FROM here."
          },
          "target": {
            "type": "string",
            "description": "Downstream node id or label — data flows TO here."
          },
          "label": {
            "type": "string",
            "description": "What this connection does. Required."
          },
          "type": {
            "type": "string",
            "enum": [
              "dataflow",
              "transformation",
              "dependency",
              "lineage",
              "join"
            ],
            "description": "Default \"dataflow\"."
          },
          "style": {
            "type": "string",
            "enum": [
              "solid",
              "dashed",
              "dotted"
            ]
          }
        },
        "required": [
          "source",
          "target",
          "label"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 60
    }
  },
  "required": [
    "diagram_id",
    "edges"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Change existing connections without deleting them: fix a label, change the type, or restyle. Use this to correct a wrong edge label rather than disconnecting and reconnecting. Operates on one Datadef diagram, named by diagram_id.

{
  "type": "object",
  "properties": {
    "diagram_id": {
      "type": "string",
      "description": "Canvas id, from list_diagrams, create_diagram, or create_blank_diagram."
    },
    "updates": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "source": {
            "type": "string",
            "description": "Source node id or label."
          },
          "target": {
            "type": "string",
            "description": "Target node id or label."
          },
          "label": {
            "type": "string",
            "description": "New label."
          },
          "type": {
            "type": "string",
            "enum": [
              "dataflow",
              "transformation",
              "dependency",
              "lineage",
              "join"
            ]
          },
          "style": {
            "type": "string",
            "enum": [
              "solid",
              "dashed",
              "dotted"
            ]
          }
        },
        "required": [
          "source",
          "target"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 40
    }
  },
  "required": [
    "diagram_id",
    "updates"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Remove the edge between two nodes. Operates on one Datadef diagram, named by diagram_id.

{
  "type": "object",
  "properties": {
    "diagram_id": {
      "type": "string",
      "description": "Canvas id, from list_diagrams, create_diagram, or create_blank_diagram."
    },
    "edges": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "source": {
            "type": "string"
          },
          "target": {
            "type": "string"
          }
        },
        "required": [
          "source",
          "target"
        ],
        "additionalProperties": false
      },
      "minItems": 1
    }
  },
  "required": [
    "diagram_id",
    "edges"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Set the full column list of a table node, replacing whatever it had. Pass every column you want to keep — this is a replace, not a merge. Mark primary and foreign keys; they are what make a data diagram worth reading. Operates on one Datadef diagram, named by diagram_id.

{
  "type": "object",
  "properties": {
    "diagram_id": {
      "type": "string",
      "description": "Canvas id, from list_diagrams, create_diagram, or create_blank_diagram."
    },
    "node": {
      "type": "string",
      "description": "Table node id or exact label."
    },
    "columns": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Column name, e.g. \"customer_id\"."
          },
          "type": {
            "type": "string",
            "description": "SQL type, e.g. \"varchar\", \"bigint\", \"timestamp\". Default \"unknown\"."
          },
          "isPrimaryKey": {
            "type": "boolean"
          },
          "isForeignKey": {
            "type": "boolean"
          },
          "description": {
            "type": "string",
            "description": "What the column means in business terms."
          }
        },
        "required": [
          "name"
        ],
        "additionalProperties": false
      },
      "maxItems": 60
    }
  },
  "required": [
    "diagram_id",
    "node",
    "columns"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Create a labelled zone (e.g. "Bronze Layer", "Ingestion") and optionally move nodes into it. Zones are what turn a tangle of boxes into a readable architecture — use them for layers, domains, or environments. Operates on one Datadef diagram, named by diagram_id. If you have not already, call get_design_guide first: it carries Datadef's size, edge, and zone standard, and diagrams built without it read poorly.

{
  "type": "object",
  "properties": {
    "diagram_id": {
      "type": "string",
      "description": "Canvas id, from list_diagrams, create_diagram, or create_blank_diagram."
    },
    "label": {
      "type": "string",
      "description": "Zone name, e.g. \"Silver Layer\"."
    },
    "description": {
      "type": "string"
    },
    "parentGroup": {
      "type": "string",
      "description": "Existing group to nest this one inside, e.g. \"Databricks Workspace\". Zones nest freely — a platform boundary containing Bronze/Silver/Gold is how architects draw."
    },
    "style": {
      "type": "string",
      "enum": [
        "layer",
        "cluster",
        "swimlane"
      ],
      "description": "layer = horizontal band (default), cluster = box, swimlane = vertical lane."
    },
    "family": {
      "type": "string",
      "enum": [
        "source",
        "ingest",
        "bronze",
        "silver",
        "gold",
        "consume",
        "dbt",
        "neutral"
      ],
      "description": "Accent hue encoding the zone role: source=teal (inputs/producers), ingest=blue (movement/processing), bronze/silver/gold=medallion layers, consume=magenta (outputs/consumers), dbt=coral (transformation projects), neutral=grey (platform). Zones with different roles get different families."
    },
    "nodes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Node ids or labels to place inside."
    }
  },
  "required": [
    "diagram_id",
    "label"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Move existing nodes into an existing group, or out of any group. Operates on one Datadef diagram, named by diagram_id.

{
  "type": "object",
  "properties": {
    "diagram_id": {
      "type": "string",
      "description": "Canvas id, from list_diagrams, create_diagram, or create_blank_diagram."
    },
    "nodes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "description": "Node ids or labels to move."
    },
    "group": {
      "type": [
        "string",
        "null"
      ],
      "description": "Target group id or label. Pass null to remove the nodes from their group."
    }
  },
  "required": [
    "diagram_id",
    "nodes",
    "group"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Record column-level lineage: which source column produces which target column, and how. This is what makes the diagram queryable for impact analysis, so add it for every real transformation. Operates on one Datadef diagram, named by diagram_id.

{
  "type": "object",
  "properties": {
    "diagram_id": {
      "type": "string",
      "description": "Canvas id, from list_diagrams, create_diagram, or create_blank_diagram."
    },
    "links": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "sourceNode": {
            "type": "string",
            "description": "Upstream node id or label."
          },
          "sourceColumn": {
            "type": "string",
            "description": "Upstream column name. Omit for table-level lineage."
          },
          "targetNode": {
            "type": "string",
            "description": "Downstream node id or label."
          },
          "targetColumn": {
            "type": "string",
            "description": "Downstream column name."
          },
          "joinType": {
            "type": "string",
            "description": "direct, transform, aggregation, lookup, filter, union, or a join kind."
          },
          "description": {
            "type": "string",
            "description": "The transformation logic in one line."
          }
        },
        "required": [
          "sourceNode",
          "targetNode"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 100
    }
  },
  "required": [
    "diagram_id",
    "links"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Place a free-floating text box on the canvas — a caption, a callout, a section heading, a note explaining a decision. Position it with explicit coordinates from canvas_measure_canvas. Text boxes are annotations: they are not part of the data flow and take no edges. Operates on one Datadef diagram, named by diagram_id.

{
  "type": "object",
  "properties": {
    "diagram_id": {
      "type": "string",
      "description": "Canvas id, from list_diagrams, create_diagram, or create_blank_diagram."
    },
    "texts": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string",
            "minLength": 1,
            "description": "The text content. Newlines are preserved."
          },
          "x": {
            "type": "number",
            "description": "Absolute x of the top-left corner."
          },
          "y": {
            "type": "number",
            "description": "Absolute y of the top-left corner."
          },
          "width": {
            "type": "number",
            "minimum": 40,
            "maximum": 1200,
            "description": "Default 220."
          },
          "height": {
            "type": "number",
            "minimum": 20,
            "maximum": 800,
            "description": "Default 60."
          },
          "fontSize": {
            "type": "number",
            "minimum": 8,
            "maximum": 72,
            "description": "Default 14."
          },
          "bold": {
            "type": "boolean"
          },
          "textColor": {
            "type": "string",
            "description": "Hex colour, e.g. \"#111827\"."
          },
          "transparent": {
            "type": "boolean",
            "description": "Draw with no box or border, for a caption floating over the canvas."
          }
        },
        "required": [
          "text",
          "x",
          "y"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 20
    }
  },
  "required": [
    "diagram_id",
    "texts"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Place a rectangle, circle, arrow, or line as a visual annotation — a backdrop highlighting a region, an arrow pointing something out, a divider. Shapes sit behind data nodes and are not part of the data flow. To group nodes into a labelled zone use canvas_group_nodes instead. Operates on one Datadef diagram, named by diagram_id.

{
  "type": "object",
  "properties": {
    "diagram_id": {
      "type": "string",
      "description": "Canvas id, from list_diagrams, create_diagram, or create_blank_diagram."
    },
    "shapes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "shape": {
            "type": "string",
            "enum": [
              "rectangle",
              "circle",
              "arrow",
              "line"
            ]
          },
          "x": {
            "type": "number"
          },
          "y": {
            "type": "number"
          },
          "width": {
            "type": "number",
            "minimum": 4,
            "maximum": 4000
          },
          "height": {
            "type": "number",
            "minimum": 1,
            "maximum": 4000
          },
          "label": {
            "type": "string",
            "description": "Text drawn on the shape."
          },
          "fillColor": {
            "type": "string",
            "description": "Hex colour."
          },
          "strokeColor": {
            "type": "string",
            "description": "Hex colour."
          }
        },
        "required": [
          "shape",
          "x",
          "y"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 20
    }
  },
  "required": [
    "diagram_id",
    "shapes"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Draw one large labelled arrow representing a whole flow — "ingest", "serve", "publish" — instead of many thin edges saying the same thing. Use this when several things move the same way for the same reason: draw the arrow once between the two areas rather than connecting every pair. This is a visual annotation, not a connection, so it adds no edges and no fan-out. Position it in the gap between the two areas using canvas_measure_canvas. Operates on one Datadef diagram, named by diagram_id.

{
  "type": "object",
  "properties": {
    "diagram_id": {
      "type": "string",
      "description": "Canvas id, from list_diagrams, create_diagram, or create_blank_diagram."
    },
    "arrows": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "minLength": 1,
            "description": "What moves, e.g. \"batch + streaming ingest\"."
          },
          "x": {
            "type": "number",
            "description": "Absolute x of the arrow's top-left corner."
          },
          "y": {
            "type": "number",
            "description": "Absolute y of the arrow's top-left corner."
          },
          "width": {
            "type": "number",
            "minimum": 40,
            "maximum": 4000,
            "description": "Length. Default 200."
          },
          "thickness": {
            "type": "number",
            "minimum": 12,
            "maximum": 400,
            "description": "How thick the arrow body is. Default 48. Big flows deserve 60-120."
          },
          "direction": {
            "type": "string",
            "enum": [
              "right",
              "left",
              "up",
              "down"
            ],
            "description": "Which way the head points. Default right."
          },
          "color": {
            "type": "string",
            "description": "Hex fill. Default a soft grey-blue."
          }
        },
        "required": [
          "label",
          "x",
          "y"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 12
    }
  },
  "required": [
    "diagram_id",
    "arrows"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Draw a labelled translucent area behind existing nodes to show they belong together, without reparenting them. Use this when the grouping is a reading aid rather than real containment, when areas would need to overlap, or when a node belongs to two ideas at once — canvas_group_nodes cannot express any of those because it moves nodes into the zone. Call canvas_measure_canvas first and size the region to enclose the nodes with roughly 24px of margin. Operates on one Datadef diagram, named by diagram_id.

{
  "type": "object",
  "properties": {
    "diagram_id": {
      "type": "string",
      "description": "Canvas id, from list_diagrams, create_diagram, or create_blank_diagram."
    },
    "regions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "minLength": 1,
            "description": "Region name, drawn at the top-left."
          },
          "x": {
            "type": "number"
          },
          "y": {
            "type": "number"
          },
          "width": {
            "type": "number",
            "minimum": 60,
            "maximum": 6000
          },
          "height": {
            "type": "number",
            "minimum": 60,
            "maximum": 6000
          },
          "color": {
            "type": "string",
            "description": "Hex fill, drawn translucent. Default a neutral slate."
          }
        },
        "required": [
          "label",
          "x",
          "y",
          "width",
          "height"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 12
    }
  },
  "required": [
    "diagram_id",
    "regions"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Set node positions precisely. Use absolute x/y to place something exactly, or dx/dy to nudge it. Coordinates are absolute canvas units (same space canvas_measure_canvas reports). Moving a group moves its children with it — do not also move those children in the same call. Call canvas_measure_canvas first. Operates on one Datadef diagram, named by diagram_id.

{
  "type": "object",
  "properties": {
    "diagram_id": {
      "type": "string",
      "description": "Canvas id, from list_diagrams, create_diagram, or create_blank_diagram."
    },
    "moves": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "node": {
            "type": "string",
            "description": "Node id or exact label."
          },
          "x": {
            "type": "number",
            "description": "Absolute x. Omit to keep current x."
          },
          "y": {
            "type": "number",
            "description": "Absolute y. Omit to keep current y."
          },
          "dx": {
            "type": "number",
            "description": "Relative horizontal shift. Ignored if x is given."
          },
          "dy": {
            "type": "number",
            "description": "Relative vertical shift. Ignored if y is given."
          }
        },
        "required": [
          "node"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 60
    }
  },
  "required": [
    "diagram_id",
    "moves"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Set the width and height of nodes. Mostly for shapes, text boxes, and group zones — data nodes size themselves from their content, and resizing one can clip what it displays. Operates on one Datadef diagram, named by diagram_id.

{
  "type": "object",
  "properties": {
    "diagram_id": {
      "type": "string",
      "description": "Canvas id, from list_diagrams, create_diagram, or create_blank_diagram."
    },
    "resizes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "node": {
            "type": "string",
            "description": "Node id or exact label."
          },
          "width": {
            "type": "number",
            "minimum": 20,
            "maximum": 4000
          },
          "height": {
            "type": "number",
            "minimum": 20,
            "maximum": 4000
          }
        },
        "required": [
          "node"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 40
    }
  },
  "required": [
    "diagram_id",
    "resizes"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Align nodes to a shared edge or centre line, or space them evenly. Cleaner and far more reliable than computing coordinates by hand. Operates on one Datadef diagram, named by diagram_id.

{
  "type": "object",
  "properties": {
    "diagram_id": {
      "type": "string",
      "description": "Canvas id, from list_diagrams, create_diagram, or create_blank_diagram."
    },
    "nodes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 2,
      "maxItems": 40,
      "description": "Node ids or labels."
    },
    "mode": {
      "type": "string",
      "enum": [
        "left",
        "right",
        "top",
        "bottom",
        "center-horizontal",
        "center-vertical",
        "distribute-horizontal",
        "distribute-vertical"
      ],
      "description": "left/right/top/bottom align edges; center-* align centre lines; distribute-* space evenly between the outermost two."
    }
  },
  "required": [
    "diagram_id",
    "nodes",
    "mode"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Merge several nodes into one summary node, keeping every connection. Use when a set of near-identical objects adds length without adding meaning — eight staging models that all behave the same become "stg_* (8)". Do not use when the individual objects are what the reader came for. Operates on one Datadef diagram, named by diagram_id.

{
  "type": "object",
  "properties": {
    "diagram_id": {
      "type": "string",
      "description": "Canvas id, from list_diagrams, create_diagram, or create_blank_diagram."
    },
    "nodes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 2,
      "maxItems": 40,
      "description": "Node ids or labels to merge. They should be genuinely similar."
    },
    "label": {
      "type": "string",
      "description": "Label for the merged node. Omit to generate one such as \"stg_* (8)\"."
    },
    "description": {
      "type": "string",
      "description": "What the merged node stands for. Defaults to listing what was collapsed."
    }
  },
  "required": [
    "diagram_id",
    "nodes"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Arrange the canvas. Call this once at the end, after all structural edits are done — not between each edit. By default only the parts you touched are re-arranged and everything else keeps its position. Operates on one Datadef diagram, named by diagram_id.

{
  "type": "object",
  "properties": {
    "diagram_id": {
      "type": "string",
      "description": "Canvas id, from list_diagrams, create_diagram, or create_blank_diagram."
    },
    "full": {
      "type": "boolean",
      "description": "Re-arrange the entire canvas from scratch, discarding existing positions. Only use when the user asks for a full reorganisation. Default false."
    }
  },
  "required": [
    "diagram_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Check the canvas for structural problems (disconnected nodes, circular data flow, broken references) and quality problems (unlabelled edges, tables without columns). Call this before you finish, and fix any errors it reports. Operates on one Datadef diagram, named by diagram_id.

{
  "type": "object",
  "properties": {
    "diagram_id": {
      "type": "string",
      "description": "Canvas id, from list_diagrams, create_diagram, or create_blank_diagram."
    }
  },
  "required": [
    "diagram_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Generate a professional data architecture diagram from a description and save it to the user's Datadef account. Use this for any data-shaped diagram: medallion and lakehouse architectures, ETL/ELT pipelines, streaming topologies, data mesh, star and snowflake schemas, ER diagrams, lineage maps, cloud architectures, and data platform designs. EXISTING SCHEMAS: if the conversation or the repository has the schema itself (SQL DDL, a MySQL or pg_dump export, migrations, schema.prisma), pass the file contents as the prompt, unedited. Datadef parses it instead of asking a model: every table, column, type, primary key and foreign key comes out exactly as written, in seconds. Warehouse DDL with no declared foreign keys (fact_sales.customer_key → dim_customer.customer_key) gets its links from key names, drawn dashed. Add a sentence only if you want something other than a picture of that schema; "turn these tables into a star schema" or "design the pipeline that loads them" goes to the model instead. Write a specific prompt. Name the actual technologies (Snowflake, dbt, Airflow, Kafka, Fivetran), the layers or zones you want, and the tables that matter, the diagram is only as detailed as the description. Zone names you give are treated as a specification, not a suggestion. SCOPE: if the user's request is open-ended ("diagram our platform", "show me something"), ask them how much detail they want before calling this, or say which scope you chose. Default to scope "overview". A dense 40-node diagram is impressive and usually not what someone wanted from a one-line request; they can always ask you to expand it. TIMING: this waits up to ~35 seconds; fast generations come back finished, with a preview image and a markdown line to show the user. Slower ones (1-3 minutes total) return a diagram_id while generation continues: call get_diagram with that id after ~60 seconds (poll every 30s) to get the finished diagram. If you cannot call tools again on your own, never leave the user empty-handed: give them the Open link, say it will be ready in about a minute, and offer to show the diagram inline when they next ask. Never call create_diagram a second time while one is still generating; you would create a duplicate and spend another credit. Do not use image generation for these. This produces a real, editable diagram.

{
  "type": "object",
  "properties": {
    "prompt": {
      "type": "string",
      "minLength": 10,
      "description": "What to diagram. Include technologies, data sources, transformations, layers, and destinations."
    },
    "name": {
      "type": "string",
      "description": "Title for the diagram. Defaults to an AI-chosen title."
    },
    "scope": {
      "type": "string",
      "enum": [
        "overview",
        "detailed"
      ],
      "description": "overview (default): ~12-20 nodes, the shape of the system, right for almost every open-ended request. detailed: every object itemised, denser and harder to read. Ask the user rather than assuming they want detailed."
    },
    "detailed": {
      "type": "boolean",
      "description": "Use a higher-tier model. Slower and roughly 10x the cost, only when the user explicitly asks for maximum quality. Independent of `scope`."
    }
  },
  "required": [
    "prompt"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Create an empty diagram and return its diagram_id, so you can build it yourself with the canvas_* tools. No AI generation runs and no credit is spent: you draw it. Use this when you want control over the result, or already know the architecture from the conversation. Use create_diagram instead when you want Datadef's model to design the whole thing from a prompt. Call get_design_guide first: it is the standard Datadef's own generator follows, and building without it produces diagrams this tool exists to avoid.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Diagram name. Defaults to \"Untitled diagram\"."
    },
    "description": {
      "type": "string",
      "description": "Optional short description."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List diagrams in the user's Datadef account, most recently updated first. Use this to find the id of a diagram before editing or exporting it.

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "description": "Max results. Default 25."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Read the full structure of a diagram: every node with its type and columns, every connection, and the groups. Use this before editing so you know what is actually there.

{
  "type": "object",
  "properties": {
    "diagram_id": {
      "type": "string",
      "description": "Canvas id, from list_diagrams, create_diagram, or create_blank_diagram."
    },
    "include_columns": {
      "type": "boolean",
      "description": "Include table column lists. Default true."
    },
    "include_image": {
      "type": "boolean",
      "description": "Attach a PNG preview and a markdown image link to show the user. Default true; pass false for structure-only reads."
    }
  },
  "required": [
    "diagram_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Change an existing diagram with a natural-language instruction, add nodes, rewire connections, add columns, reorganise into layers, fill in owners and schedules. Be specific about what to change and where. "Add a Kafka topic between the API and the bronze table, labelled 'events'" works; "make it better" does not. Returns a PNG of the updated diagram.

{
  "type": "object",
  "properties": {
    "diagram_id": {
      "type": "string",
      "description": "Canvas id to modify."
    },
    "instruction": {
      "type": "string",
      "minLength": 3,
      "description": "What to change, in plain language."
    },
    "include_image": {
      "type": "boolean",
      "description": "Return a PNG of the updated diagram. Default true."
    }
  },
  "required": [
    "diagram_id",
    "instruction"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Render a diagram to a PNG or JPEG image. Returns the image inline AND a short-lived signed download URL. Use the inline image to show the diagram; use the URL when the user wants to save it, attach it, or share a link: it serves the file directly and needs no API key.

{
  "type": "object",
  "properties": {
    "diagram_id": {
      "type": "string",
      "description": "Canvas id to export."
    },
    "format": {
      "type": "string",
      "enum": [
        "png",
        "jpeg"
      ],
      "description": "Default png."
    },
    "width": {
      "type": "integer",
      "minimum": 600,
      "maximum": 4000,
      "description": "Viewport width in pixels. Default 1600."
    },
    "height": {
      "type": "integer",
      "minimum": 400,
      "maximum": 4000,
      "description": "Viewport height in pixels. Default 1000."
    }
  },
  "required": [
    "diagram_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

For a diagram that was created from a connected git repository: which repo and branch or tag it tracks, when it last synced, the commit it reflects, and whether daily sync is on. Use repo_refresh to sync it now. Only the owner of the repository connection can use this.

{
  "type": "object",
  "properties": {
    "project_id": {
      "type": "string",
      "description": "Project id of the repo-linked diagram. A diagram_id from list_diagrams works too."
    }
  },
  "required": [
    "project_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Re-sync a repo-linked diagram from the current state of its repository. If the tracked branch or tag has not moved since the last sync, nothing changes. If it has, the diagram is REGENERATED from the repository, which replaces manual canvas edits. Only the owner of the repository connection can use this.

{
  "type": "object",
  "properties": {
    "project_id": {
      "type": "string",
      "description": "Project id of the repo-linked diagram. A diagram_id from list_diagrams works too."
    }
  },
  "required": [
    "project_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}