---
title: "Tools for a model"
description: "An AI model, such as a large language model (LLM), can insert, read and change charts and diagrams through tool calls."
canonical_url: "https://tiptap-docs.lin52025i.qzz.io/diagrams/guides/ai"
---

# Tools for a model

An AI model, such as a large language model (LLM), can insert, read and change charts and diagrams through tool calls.

Run the tool calls a model would make, and see each answer and its effect on the document:

> **Interactive demo:** [DiagramsModelTools](https://embed-pro.tiptap.dev/preview/Extensions/DiagramsModelTools)

## Quick start

Offer the model the chart tools and the diagram tools. Answer each tool call with the matching
run function:

```ts
import {
  getChartToolDefinitions,
  getDiagramToolDefinitions,
  runChartTool,
  runDiagramTool,
} from '@tiptap-pro/extension-diagrams'

const tools = [...getChartToolDefinitions(editor), ...getDiagramToolDefinitions(editor)]

// A call to a chart tool
const result = runChartTool(editor, name, input)
// A call to a diagram tool
const other = runDiagramTool(editor, name, input)
```

## Functions

| Function                              | Returns                                                                                                                                          |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `getChartToolDefinitions(editor)`     | Tool definitions (`name`, `description`, `inputSchema`) for the [chart tools](https://tiptap-docs.lin52025i.qzz.io/diagrams/guides/ai.md#charts) |
| `runChartTool(editor, name, input)`   | `{ ok, output, pos? }` after running one chart tool                                                                                              |
| `getDiagramToolDefinitions(editor)`   | Tool definitions for the [diagram tools](https://tiptap-docs.lin52025i.qzz.io/diagrams/guides/ai.md#diagrams)                                    |
| `runDiagramTool(editor, name, input)` | `{ ok, output, pos? }` after running one diagram tool                                                                                            |

## What a call returns

| Field    | Type      | Description                                                                                              |
| -------- | --------- | -------------------------------------------------------------------------------------------------------- |
| `ok`     | `boolean` | Whether the call succeeded                                                                               |
| `output` | `string`  | JSON, or on failure a message that tells the model how to fix the call                                   |
| `pos`    | `number`  | The position of the chart or diagram that an insert or an update wrote. The end of `output` names it too |

## Charts

The chart tools are `insertChart`, `insertLinkedChart`, `updateChart`, `readChart`, `listCharts`
and `describeChartCapabilities`. Their definitions list the formats and Renderers of your editor
as enums.

### Only what this editor can draw

The tools never insert a chart that no registered Renderer can draw. The `type` enum lists the
chart types that a registered Renderer draws, and `describeChartCapabilities` names the types of
each Renderer.

These calls are refused, and nothing is written:

- an insert of a chart that no Renderer draws
- a `renderer` that is not registered, or that does not draw the chart's type
- an `updateChart` call that changes the type to one no Renderer draws

The answer names the types or Renderers to use instead:

```json
{
  "ok": false,
  "output": "No Renderer here draws \"sankey\" charts. Use one of these types: line, bar, pie."
}
```

### A chart that reads a Data Source

The tool `insertLinkedChart` inserts a chart and links it to a [Data Source](https://tiptap-docs.lin52025i.qzz.io/diagrams/data/sources.md), such
as a CSV file at a URL, with `linkChartSource`. The command of the same name,
[`insertLinkedChart`](https://tiptap-docs.lin52025i.qzz.io/diagrams/data/tables.md#insertlinkedchart), is different: it makes a chart that
follows a table in the document. The tool cannot do that, because it does not offer the
`document-table` source.

| Parameter  | Type      | Description                                                                         |
| ---------- | --------- | ----------------------------------------------------------------------------------- |
| `provider` | `string`  | The Data Source. An enum of the registered Data Sources other than `document-table` |
| `address`  | `object`  | Where the source reads from, such as `{ url }` for a CSV or JSON file at a URL      |
| `type`     | `string`  | The chart type. Optional                                                            |
| `title`    | `string`  | The chart's title. Optional                                                         |
| `readOnly` | `boolean` | The chart is read-only unless this is `false`                                       |

The data arrives after the call returns. A failed read goes to `onSourceError`. The tool links
`url-csv` and `url-json` only when your app sets [`allowSourceUrl`](https://tiptap-docs.lin52025i.qzz.io/diagrams/api-reference/options.md#allowsourceurl),
and only to the URLs it allows. `allowSourceUrl` decides where a request may go, not what the URL
holds.
A model can still put document text into an allowed URL, for example in its query. So allow only
hosts you trust with the document's content.

## Diagrams

The diagram tools are `insertDiagram`, `updateDiagram`, `readDiagram` and `listDiagrams`. A model
writes Mermaid, which it already knows. `listDiagrams` names each diagram's `format`. A draw\.io or
BPMN diagram is read and changed as its whole XML.

A [Mermaid chart kind](https://tiptap-docs.lin52025i.qzz.io/diagrams/charts/overview.md#importmermaidchart), such as a pie, is a chart. A diagram tool call with one is
refused, with a message that points the model to `insertChart`.

### Formats and Renderers

- **`insertDiagram` creates Mermaid or BPMN.** For BPMN, the call passes `format: 'bpmn'`. Without
  a `format`, it creates Mermaid, unless your editor draws BPMN but not Mermaid.
- **`insertDiagram` does not offer draw\.io.** Its `format` enum is `mermaid` and `bpmn`. The
  model can read and change an existing draw\.io diagram with `readDiagram` and `updateDiagram`.
- **The tools write the source whatever Renderers are registered**, as the commands do. A format
  or a kind that no Renderer here draws is written all the same. The `output` tells the model that
  it shows as unavailable in this editor.