---
title: "Tools for a model"
description: "A model inserts, reads and changes charts and diagrams through tool calls."
canonical_url: "https://tiptap.dev/docs/diagrams/guides/ai"
---

# Tools for a model

A model inserts, reads and changes 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 chart tools beside the diagram tools, and answer each 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.dev/docs/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.dev/docs/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 saying how to fix the call                                   |
| `pos`    | `number`  | The chart or diagram an insert or an update wrote. It is also named at the end of `output` |

## Charts

The chart tools are `insertChart`, `insertLinkedChart`, `updateChart`, `readChart`, `listCharts`
and `describeChartCapabilities`. The formats and Renderers of this editor appear in their
definitions as enums.

### Only what this editor can draw

- **The `type` enum** lists the chart types a registered Renderer draws.
- **`describeChartCapabilities`** names the types of each Renderer.
- **A call that would insert a chart nobody sees** is refused, with the types or Renderers to
  use instead. Nothing is written.
- **A `renderer` that is not registered**, or that does not draw the chart's type, is refused
  the same way.
- **An `updateChart` that changes the type** to one nobody draws is refused the same way.

```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

`insertLinkedChart` inserts a chart and links it to a Data Source with `linkChartSource`.

| Parameter  | Type      | Description                                                          |
| ---------- | --------- | -------------------------------------------------------------------- |
| `provider` | `string`  | 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 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`.

## Diagrams

The diagram tools are `insertDiagram`, `updateDiagram`, `readDiagram` and `listDiagrams`.

- A model writes Mermaid, which it already knows.
- A call with a pie, an xychart, a sankey, a radar or a treemap is refused with a message
  pointing at `insertChart`.
- `listDiagrams` names each diagram's `format`.
- A draw\.io or BPMN diagram is read and changed as its whole XML.

### Formats and Renderers

- **`insertDiagram` creates Mermaid**, or BPMN with `format: 'bpmn'`.
- **The tools write the source whatever is registered**, as the Commands do. The source belongs
  to the document; a Renderer only draws it.
- **A format or a kind no Renderer here draws** is written all the same. The `output` tells the
  model that it shows as unavailable here.