When: use when Datadef's own model should design a whole new diagram from a description or a pasted schema. To build it yourself step by step, use create_blank_diagram; to change an existing diagram, canvas_view and the canvas_* tools, or edit_diagram.
Generates a professional data architecture diagram from a description and saves it to the user's Datadef account. Use it 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.
Do not use image generation for these. This produces a real, editable diagram.
Next: show the user the preview line it returns; to adjust the result, canvas_view then the targeted canvas_* tools.