# MCP tools

Advanced reference for the DrawSQL MCP server. Look up tool inputs, outputs, errors, limits, and annotations. For client setup and a first diagram, start with the getting started guide.

## How tools respond

The server is at `https://drawsql.app/mcp` over streamable HTTP. Every tool returns one text block, written in Markdown for the model to read. An error is a tool result too: `isError` is `true` and the text says what went wrong and how to fix it. Some error messages begin with their code, such as `invalid_request:`; the tables below show which.

Tools that create something reply with counts, never with your table or column names, so a reply cannot carry instructions hidden in a schema. `get_schema` is the exception: returning the schema is its job.

## Authentication

`visualize_schema` needs no account. Every other tool needs a DrawSQL API token, sent on the MCP connection as an `Authorization: Bearer <token>` header. Create one under [Account → API tokens](/user/api-tokens). Tokens are available on paid plans, and each token belongs to one team.

The tool list depends on the header:

| Connection | Tools it adds to the list |
| --- | --- |
| No `Authorization` header | `visualize_schema` |
| Any bearer token | `list_diagrams`, `get_schema`, `get_diagram_link` |
| Any bearer token, for the write loop | `get_driver_rules`, `get_proposal_status` |
| A token with **Read and write** access | `create_diagram`, `propose_diagram_changes` |

Each row adds to the rows above it.

The list checks only that a header is present; write tools also need a token with write access. The token itself is checked on every call. Calling a tool that is not in your list returns a JSON-RPC error, code `-32602`, message `Tool [name] not found.`

These errors can come from any tool that needs a token:

| Code | When | The agent reads |
| --- | --- | --- |
| `invalid_token` | The token is unknown, expired, or revoked. | "This API token is invalid, expired, or revoked. Create a new one under Account → API tokens." |
| `invalid_token` | The token's team is gone, or its user left the team. | "This API token no longer grants access (its team or membership is gone)…" |
| `plan_required` | The token's team is not on a paid plan. | "The DrawSQL API requires a paid plan. Upgrade the team "…" to restore access." |

A token sees the diagrams its user can see in the token's team. It reads the same diagrams as the [REST API](/docs/api).

## Rate limits

| Limit | Applies to | Over the limit |
| --- | --- | --- |
| 20 requests / minute, per IP | Every request to `/mcp`, including `initialize` and `tools/list` | HTTP `429` with a `Retry-After` header |
| 10 calls / minute, per IP | `visualize_schema` | Tool error `rate_limited`: "Too many `visualize_schema` calls. Try again in N seconds." |
| 10 calls / minute, per token, for each tool | `create_diagram` and `propose_diagram_changes`, counted separately | Tool error `rate_limited`: "Too many create_diagram calls. Try again in N seconds." |

The read tools have no limit of their own beyond the 20 requests a minute on the endpoint. The `x-ratelimit-*` response headers describe the endpoint limit, not the tool limits.

## Call order

- **Read a diagram:** `list_diagrams` → `get_schema`. Add `get_diagram_link` when you need a URL to cite.
- **Show a schema you have as a diagram, with no account:** `visualize_schema`.
- **Change an existing diagram:** `list_diagrams` → `get_schema` → `get_driver_rules` → `propose_diagram_changes` → `get_proposal_status`.
- **Create a diagram:** `get_driver_rules` (when you send a patch) → `create_diagram` → `get_diagram_link` until the status is `ready` → `get_schema`.

## `visualize_schema`

Turns SQL DDL or a DrawSQL schema patch into an editable diagram and returns a `drawsql.app/draw` link.

**Auth:** none. **REST twin:** none.

**Inputs.** Send exactly one of `ddl` and `schema`.

| Name | Type | Required | Limits |
| --- | --- | --- | --- |
| `ddl` | string | Yes, unless `schema` is set | SQL `CREATE TABLE` and `ALTER TABLE` statements. Up to 200,000 bytes. |
| `schema` | string | Yes, unless `ddl` is set | A [schema patch](/reference/schema-patch) encoded as a JSON string. Up to 500,000 bytes. Omit `deletions`: every call makes a new diagram. |
| `driver` | string | No | `mysql`, `pgsql`, or `sqlsrv`. Defaults to `mysql`. |

**Output.** The link, then a summary: driver and counts of tables, columns, and relationships, plus groups, sticky notes, and indexes when there are any. A note follows when the input had more than 20 tables (the link opens the first 20) or when a column type was mapped to the driver's nearest type.

The link needs no account. A link nobody opens expires after 30 days. Opening it extends the expiry to one year from that view.

**Errors**

| Code | When | The agent reads |
| --- | --- | --- |
| `invalid_input` | Neither or both of `ddl` and `schema`, or a value that is not a string. | "Received both `ddl` and `schema`. Provide exactly one." |
| `invalid_driver` | `driver` is not a supported value. | "The `driver` value is not supported. Use one of: mysql, pgsql, sqlsrv…" |
| `payload_too_large` | `ddl` over 200KB, or `schema` over 500KB. | "The SQL is too large (max 200KB). Trim it and try again." |
| `invalid_json` | `schema` is not valid JSON. | "The `schema` value is not valid JSON." |
| `no_tables` | The DDL or patch has no tables. | "No tables were found in the SQL…" |
| `invalid_schema` | The patch breaks the format. Every problem is listed in one reply, each naming its field. | "Invalid schema patch: tables[0].name has leading or trailing whitespace. Send the exact text." |
| `parse_failed` | The SQL could not be parsed. | "Could not parse the SQL. Check the DDL syntax and try again." |
| `rate_limited` | More than 10 calls in a minute from one IP. | "Too many `visualize_schema` calls. Try again in N seconds." |

**Example**

```json
{
  "name": "visualize_schema",
  "arguments": {
    "driver": "pgsql",
    "schema": "{\"tables\":[{\"name\":\"users\",\"columns\":[{\"name\":\"id\",\"type\":\"bigint\",\"is_primary_key\":true},{\"name\":\"email\",\"type\":\"varchar\"}]},{\"name\":\"orders\",\"columns\":[{\"name\":\"id\",\"type\":\"bigint\",\"is_primary_key\":true},{\"name\":\"user_id\",\"type\":\"bigint\"},{\"name\":\"total\",\"type\":\"decimal\"}]}],\"relationships\":[{\"type\":\"one-to-many\",\"source_table\":\"users\",\"source_column\":\"id\",\"target_table\":\"orders\",\"target_column\":\"user_id\"}]}"
  }
}
```

```text
Your diagram is ready: https://drawsql.app/draw?t=6ce7d8c1-3b55-4c3f-b075-e12330536714&utm_source=mcp

Open the link to view, edit, share, or export the diagram. No account is required.

**Summary**
- Driver: pgsql
- Tables: 2
- Columns: 5
- Relationships: 1
```

**Rate limit:** 10 calls a minute per IP.

**Annotations**

| Hint | Value | Why |
| --- | --- | --- |
| `readOnlyHint` | `false` (not sent) | It stores the schema and creates a new link. |
| `destructiveHint` | `false` | It only adds a new link; nothing that exists is changed or removed. |
| `openWorldHint` | `false` | It reaches only DrawSQL, never a third-party system. |

**Call order:** use it whenever the agent can see a schema the user wants as a diagram. It needs nothing first.

## `list_diagrams`

Lists the diagrams visible to the token, newest first.

**Auth:** bearer token. **REST twin:** [`GET /v1/diagrams`](/reference/api#tag/diagrams/GET/diagrams).

**Inputs**

| Name | Type | Required | Limits |
| --- | --- | --- | --- |
| `limit` | integer | No | 1–100; values outside the range are clamped. Defaults to 25. |
| `cursor` | string | No | The cursor from a previous reply. Omit it for the first page. |

**Output.** The team name and the number of diagrams on this page, then one line per diagram: name, table count, status (`ready`, `importing`, or `failed` with its error code), id (the diagram's uuid), and URL. When more pages exist, the last line gives the cursor for the next one. Names are flattened to one line and their Markdown is escaped.

**Errors**

| Code | When | The agent reads |
| --- | --- | --- |
| `invalid_token`, `plan_required` | See [Authentication](#authentication). | |
| `invalid_cursor` | The cursor was not issued by this tool. | "The cursor is not one this tool issued. Omit it to start from the first page." |

**Example**

```json
{ "name": "list_diagrams", "arguments": { "limit": 25 } }
```

```text
**Acme** — 1 diagram visible to this token:
- **Orders service** — 2 tables — status: ready — id: `030c01ac-2b43-409f-83e8-85d1e38b311e` — https://drawsql.app/teams/acme/diagrams/orders-service
```

**Rate limit:** the endpoint limit only.

**Annotations**

| Hint | Value | Why |
| --- | --- | --- |
| `readOnlyHint` | `true` | It only reads diagram metadata. |
| `destructiveHint` | not sent | Clients ignore it on a read-only tool. |
| `openWorldHint` | `false` | It reads only DrawSQL. |

**Call order:** call it first. The id it returns is the `diagram` input of `get_schema` and `get_diagram_link`.
It is also the first step before `propose_diagram_changes`.

## `get_schema`

Returns a diagram's schema as compact Markdown: tables, columns, types, keys, relationships, groups, indexes, and notes.

**Auth:** bearer token. **REST twin:** [`GET /v1/diagrams/{uuid}/schema?format=ai`](/reference/api#tag/diagrams/GET/diagrams/{uuid}/schema), which returns the same text.

**Inputs**

| Name | Type | Required | Limits |
| --- | --- | --- | --- |
| `diagram` | string | Yes | The diagram's id (uuid) from `list_diagrams`. |
| `level` | string | No | `detailed` (types and constraints, the default) or `simple` (column names only). |

**Output.** The schema in the AI Schema Format. At `detailed`, columns are `NOT NULL` unless marked `nullable`. This is the same text as the editor's **Take to your AI**.

If the diagram's live editing session holds edits that are not saved yet, the tool saves them first, the same way autosave does, so it reads the current diagram.

**Errors**

| Code | When | The agent reads |
| --- | --- | --- |
| `invalid_token`, `plan_required` | See [Authentication](#authentication). | |
| `invalid_input` | `level` is not `simple` or `detailed`. | "level must be one of: simple, detailed." |
| `not_found` | The id is unknown, malformed, or not visible to the token. All three read the same. | "No diagram with that id is visible to this token. Use list_diagrams to see what is." |
| `diagram_not_ready` | The diagram is still importing. | "diagram_not_ready: this diagram is still importing. Poll get_diagram_link until status is ready." |

**Example**

```json
{ "name": "get_schema", "arguments": { "diagram": "030c01ac-2b43-409f-83e8-85d1e38b311e" } }
```

```text
# Schema: Orders service
Database: pgsql
Tables: 2
Columns are NOT NULL unless marked nullable.

## users
id: bigint PK
email: varchar

## orders
id: bigint PK
user_id: bigint FK
total: decimal

## Relationships
users.id → orders.user_id (one-to-many)
```

**Rate limit:** the endpoint limit only.

**Annotations**

| Hint | Value | Why |
| --- | --- | --- |
| `readOnlyHint` | `false` (not sent) | It can save the diagram's unsaved live edits before it reads. |
| `destructiveHint` | `false` | That save stores the diagram as people left it; it never removes or changes their work. |
| `openWorldHint` | `false` | It reads only DrawSQL. |

`idempotentHint` is `true`: once the save has run, a repeat call with the same arguments writes nothing.

**Call order:** after `list_diagrams`. Read it before writing a query or a migration against the schema.
Read it before `propose_diagram_changes` too, so the patch names tables and columns that exist.

## `get_diagram_link`

Returns a diagram's canonical URL and embed URL, to cite or share.

**Auth:** bearer token. **REST twin:** [`GET /v1/diagrams/{uuid}`](/reference/api#tag/diagrams/GET/diagrams/{uuid}).

**Inputs**

| Name | Type | Required | Limits |
| --- | --- | --- | --- |
| `diagram` | string | Yes | The diagram's id (uuid) from `list_diagrams`. |

**Output.** The diagram name, its URL, its embed URL, and its status: `ready`, `importing`, or `failed` with an error code.

**Errors**

| Code | When | The agent reads |
| --- | --- | --- |
| `invalid_token`, `plan_required` | See [Authentication](#authentication). | |
| `not_found` | The id is unknown, malformed, or not visible to the token. | "No diagram with that id is visible to this token. Use list_diagrams to see what is." |

**Example**

```json
{ "name": "get_diagram_link", "arguments": { "diagram": "030c01ac-2b43-409f-83e8-85d1e38b311e" } }
```

```text
**Orders service**
- URL: https://drawsql.app/teams/acme/diagrams/orders-service
- Embed URL: https://drawsql.app/teams/acme/diagrams/orders-service/embed
- Status: ready
```

**Rate limit:** the endpoint limit only.

**Annotations**

| Hint | Value | Why |
| --- | --- | --- |
| `readOnlyHint` | `true` | It only reads diagram metadata. |
| `destructiveHint` | not sent | Clients ignore it on a read-only tool. |
| `openWorldHint` | `false` | It reads only DrawSQL. |

**Call order:** after `list_diagrams`, whenever the answer should link to the diagram.
After `create_diagram` returns `importing`, call it every 5 seconds until the status is `ready` or `failed`.

## `get_driver_rules`

Returns the rules for writing a schema patch for one driver: its data types, the patch format, the size limits, and the call order.

**Auth:** bearer token. **REST twin:** [`GET /v1/data-types?driver=`](/reference/api#tag/data-types/GET/data-types) and [`GET /v1/schema-patch-contract`](/reference/api#tag/schema-patch/GET/schema-patch-contract).

**Inputs**

| Name | Type | Required | Limits |
| --- | --- | --- | --- |
| `driver` | string | Yes | `mysql`, `pgsql`, or `sqlsrv`. Use the driver of the diagram you are changing. |

**Output.** Three Markdown sections:

- **Data types:** one line per type the driver accepts, with its params, its cross-driver family, and its aliases. It is the same list as `GET /v1/data-types`.
- **Patch format:** every section of the patch and the fields it takes, the relationship types, the size limits, which tool accepts positions and sizes, and how retries behave.
- **Call order:** the five steps for a change.

**Errors**

| Code | When | The agent reads |
| --- | --- | --- |
| `invalid_token`, `plan_required` | See [Authentication](#authentication). | |
| `invalid_request` | `driver` is missing or not supported. | "invalid_request: `driver` must be one of: mysql, pgsql, sqlsrv." |

**Example**

```json
{ "name": "get_driver_rules", "arguments": { "driver": "pgsql" } }
```

```text
## Data types (pgsql)
- bigint · family: bigInteger · aliases: int8
- bigserial · family: bigSerialPgsql
- boolean · family: boolean · aliases: bool
…
- varchar (params: length) · family: string · aliases: character varying

## Patch format
Top-level sections and the fields each documents:
- `strategy`: merge or additive
- `tables[]`: name, old_name, comment, parent_uuid, parent_name, left, top, columns, indexes
…
- Size limits: `ddl` ≤ 200KB, `schema` ≤ 500KB.

## Call order
`list_diagrams → get_schema → get_driver_rules → propose_diagram_changes → get_proposal_status`
…
```

**Rate limit:** the endpoint limit only.

**Annotations**

| Hint | Value | Why |
| --- | --- | --- |
| `readOnlyHint` | `true` | It reads the data-type catalog and the patch format. |
| `destructiveHint` | not sent | Clients ignore it on a read-only tool. |
| `openWorldHint` | `false` | It reads only DrawSQL. |

`idempotentHint` is `true`: the same driver returns the same rules until DrawSQL ships new types.

**Call order:** after `get_schema`, before `propose_diagram_changes` or a `create_diagram` call that sends a patch.

## `get_proposal_status`

Returns where a proposal stands: `pending`, `applied`, `declined`, or `expired`.

**Auth:** bearer token; read access is enough. **REST twin:** [`GET /v1/proposals/{uuid}`](/reference/api#tag/proposals/GET/proposals/{uuid}).

**Inputs**

| Name | Type | Required | Limits |
| --- | --- | --- | --- |
| `uuid` | string | Yes | The proposal uuid that `propose_diagram_changes` returned. |

**Output.** One `label: value` line per field that has a value: `state`, `opened`, `applied`, `applied_version` (the uuid of the version the apply created), `declined`, `decline_reason`, and `expires`. Times are ISO 8601. A pending proposal adds a line asking the agent to hand the user the review link and poll again. An expired one adds a line saying an editor can reopen it.

A pending proposal past its expiry reads as `expired` at once.

**Errors**

| Code | When | The agent reads |
| --- | --- | --- |
| `invalid_token`, `plan_required` | See [Authentication](#authentication). | |
| `not_found` | The uuid is unknown, or the proposal is on a diagram the token cannot see. Both read the same. | "No proposal with that uuid is visible to this token." |

**Example**

```json
{ "name": "get_proposal_status", "arguments": { "uuid": "8b404a64-9a03-440b-9e33-7deb23d2286c" } }
```

```text
state: pending
expires: 2026-10-31T05:58:54+00:00

Ask the user to open the review link; poll again for the outcome.
```

**Rate limit:** the endpoint limit only.

**Annotations**

| Hint | Value | Why |
| --- | --- | --- |
| `readOnlyHint` | `true` | It only reads the proposal. |
| `destructiveHint` | not sent | Clients ignore it on a read-only tool. |
| `openWorldHint` | `false` | It reads only DrawSQL. |

`idempotentHint` is `true`: polling never changes the proposal.

**Call order:** last, after `propose_diagram_changes`. A declined proposal is closed: act on `decline_reason` by sending a new proposal.

## `create_diagram`

Creates a private diagram in the token's team from SQL DDL or a schema patch.

**Auth:** a token with **Read and write** access. **REST twin:** [`POST /v1/diagrams`](/reference/api#tag/diagrams/POST/diagrams).

**Inputs.** Send exactly one of `ddl` and `schema`.

| Name | Type | Required | Limits |
| --- | --- | --- | --- |
| `ddl` | string | Yes, unless `schema` is set | SQL `CREATE TABLE` and `ALTER TABLE` statements. Up to 200,000 bytes. |
| `schema` | string | Yes, unless `ddl` is set | A [schema patch](/reference/schema-patch) encoded as a JSON object string. Up to 500,000 bytes. Positions and sizes (`left`, `top`, `width`, `height`) are rejected: DrawSQL computes the layout. |
| `name` | string | No | Up to 255 characters. Defaults to `Untitled`. |
| `driver` | string | No | `mysql`, `pgsql`, or `sqlsrv`. Defaults to `mysql`. |

**Output.** The diagram's URL and uuid, then a summary: driver and counts of tables, columns, and relationships, plus groups, sticky notes, and indexes when there are any. Ignored patch fields come back as notes.

The call returns within 15 seconds. A DDL import still running then comes back as `Diagram created, import in progress`, with a line to poll `get_diagram_link` in 5 seconds; `get_schema` fails with `diagram_not_ready` until the import is `ready`. An import that cannot finish reports `Diagram created but the import failed (code): …`. The same call repeated within 120 seconds (same token, name, driver, and payload) returns the diagram it already made, starting with `Already created N seconds ago.`

The team's plan sets how many tables a diagram may hold and how many private diagrams the team may have.

**Errors**

| Code | When | The agent reads |
| --- | --- | --- |
| `invalid_token`, `plan_required` | See [Authentication](#authentication). | |
| `insufficient_scope` | The token has no write access. Usually the tool is not listed at all; this shows when a client calls it from an outdated list. | "insufficient_scope: this token cannot write. Mint a token with the write ability." |
| `not_available` | Writes are switched off. | "This tool is not available right now. Refresh the tool list." |
| `rate_limited` | More than 10 calls in a minute on this token. | "Too many create_diagram calls. Try again in N seconds." |
| `forbidden` | The token's user cannot create diagrams in the token's team. | "forbidden: this token's user cannot create diagrams in the token's team." |
| `invalid_request` | Neither or both inputs, an empty `ddl`, a `schema` that is not a JSON object, an unsupported `driver`, or a `name` over 255 characters. | "invalid_request: Send exactly one of `ddl` or `schema`." |
| `payload_too_large` | `ddl` over 200KB, or `schema` over 500KB. | "payload_too_large: The schema is too large (max 500KB)." |
| `unsupported_field` | The patch carries positions or sizes. | "unsupported_field: Positions and sizes are not accepted when creating a diagram; the layout is computed. Remove: tables[0].left." |
| `invalid_schema` | The patch breaks the format. | "invalid_schema: Invalid schema patch: …" |
| `no_tables` | The patch has no tables. | "no_tables: The schema patch has no `tables`. Include at least one table." |
| `plan_limit` | The patch has more tables than the plan allows per diagram, or the team has no private diagrams left. | "plan_limit: The schema has N tables; this team's plan allows M per diagram." |

A DDL import that fails after the call returns does not produce a tool error. The diagram's status becomes `failed` with one of `parse_failed`, `no_tables`, `plan_limit`, or `import_failed`, and `list_diagrams` and `get_diagram_link` show it.

**Example**

```json
{
  "name": "create_diagram",
  "arguments": {
    "name": "Orders service",
    "driver": "pgsql",
    "schema": "{\"tables\":[{\"name\":\"users\",\"columns\":[{\"name\":\"id\",\"type\":\"bigint\",\"is_primary_key\":true},{\"name\":\"email\",\"type\":\"varchar\"}]},{\"name\":\"orders\",\"columns\":[{\"name\":\"id\",\"type\":\"bigint\",\"is_primary_key\":true},{\"name\":\"user_id\",\"type\":\"bigint\"},{\"name\":\"total\",\"type\":\"decimal\"}]}],\"relationships\":[{\"type\":\"one-to-many\",\"source_table\":\"users\",\"source_column\":\"id\",\"target_table\":\"orders\",\"target_column\":\"user_id\"}]}"
  }
}
```

```text
Diagram created: https://drawsql.app/teams/acme/diagrams/orders-service
uuid: 030c01ac-2b43-409f-83e8-85d1e38b311e

**Summary**
- Driver: pgsql
- Tables: 2
- Columns: 5
- Relationships: 1
```

**Rate limit:** 10 calls a minute per token.

**Annotations**

| Hint | Value | Why |
| --- | --- | --- |
| `readOnlyHint` | `false` (not sent) | It creates a diagram. |
| `destructiveHint` | `false` | It only adds a new diagram; nothing that exists is overwritten or removed. |
| `openWorldHint` | `false` | It writes only to DrawSQL. |

`idempotentHint` is `false`: an identical call within 120 seconds returns the same diagram, but after that a repeat creates another one.

**Call order:** call `get_driver_rules` first when you send a patch. After an `importing` reply, poll `get_diagram_link`, then read the result with `get_schema`.

## `propose_diagram_changes`

Proposes a schema patch to an existing diagram. Nothing changes until an editor reviews the proposal in DrawSQL and applies it.

**Auth:** a token with **Read and write** access, whose user can edit the diagram. **REST twin:** [`POST /v1/diagrams/{uuid}/proposals`](/reference/api#tag/proposals/POST/diagrams/{uuid}/proposals).

**Inputs**

| Name | Type | Required | Limits |
| --- | --- | --- | --- |
| `diagram` | string | Yes | The diagram's id (uuid) from `list_diagrams`. |
| `schema` | string | Yes | A [schema patch](/reference/schema-patch) encoded as a JSON object string. Up to 500,000 bytes. The full format applies, including `deletions`, renames, groups, sticky notes, and positions and sizes. |
| `title` | string | Yes | A short title, like a pull request title. 1–100 characters. |
| `message` | string | Yes | Why the change is needed. 1–500 characters. The reviewer reads it before deciding. |

**Output.** The review link, the proposal's uuid, its expiry (30 days), and counts of the tables, columns, and relationships the patch names, plus groups, sticky notes, and deletions when there are any. A last line asks the agent to hand the user the link and poll `get_proposal_status`.

The patch is checked for shape when you send it. The reviewer's editor applies it to the diagram as it is at review time. See [Reviewing a proposal](/docs/mcp#reviewing-a-proposal).

**Errors**

| Code | When | The agent reads |
| --- | --- | --- |
| `invalid_token`, `plan_required` | See [Authentication](#authentication). | |
| `insufficient_scope` | The token has no write access (only from an outdated tool list). | "insufficient_scope: this token cannot write. Mint a token with the write ability." |
| `not_available` | Writes are switched off. | "This tool is not available right now. Refresh the tool list." |
| `rate_limited` | More than 10 calls in a minute on this token. | "Too many propose_diagram_changes calls. Try again in N seconds." |
| `not_found` | The diagram id is unknown, malformed, or not visible to the token. | "No diagram with that id is visible to this token. Use list_diagrams to see what is." |
| `invalid_request` | `schema` is missing or not a JSON object, or `title` or `message` is missing, empty, or too long. | "invalid_request: `title` is required: a string of 1 to 100 characters." |
| `payload_too_large` | `schema` over 500KB. | "payload_too_large: The schema is too large (max 500KB)." |
| `editor_required` | The token's user can view the diagram but not edit it. | "editor_required: Proposals need an editor: this token's user can view this diagram but cannot edit it." |
| `diagram_not_ready` | The diagram is still importing. | "diagram_not_ready: This diagram is still importing…" |
| `invalid_schema` | The patch breaks the format. | "invalid_schema: Invalid schema patch: …" |

**Example**

```json
{
  "name": "propose_diagram_changes",
  "arguments": {
    "diagram": "030c01ac-2b43-409f-83e8-85d1e38b311e",
    "title": "Add order notes",
    "message": "Support needs free-text notes on orders.",
    "schema": "{\"tables\":[{\"name\":\"orders\",\"columns\":[{\"name\":\"notes\",\"type\":\"text\",\"is_nullable\":true}]}]}"
  }
}
```

```text
Proposal created for review: https://drawsql.app/teams/acme/diagrams/orders-service?proposal=8b404a64-9a03-440b-9e33-7deb23d2286c
uuid: 8b404a64-9a03-440b-9e33-7deb23d2286c
expires: 2026-10-31T05:58:54+00:00

**Summary**
- Tables: 1
- Columns: 1
- Relationships: 0

Ask the user to open the link to review and apply the changes. Nothing changes until an editor applies it. Poll `get_proposal_status` with the uuid for the outcome.
```

**Rate limit:** 10 calls a minute per token.

**Annotations**

| Hint | Value | Why |
| --- | --- | --- |
| `readOnlyHint` | `false` (not sent) | It stores a proposal. |
| `destructiveHint` | `false` | Nothing is applied without an editor, even when the patch deletes tables. |
| `openWorldHint` | `false` | It writes only to DrawSQL. |

`idempotentHint` is `false`: every call creates a new proposal, so retry only a call that returned no uuid.

**Call order:** after `list_diagrams`, `get_schema`, and `get_driver_rules`. Then hand the user the review link and poll `get_proposal_status` with the uuid.
