Frontend Tool Specifications
A frontend tool runs on the page, beside the agent's conversation: it reads
or changes what the person has on screen — a notebook, a document, a
spreadsheet, a deck. Frontend tool specs (agentspecs/frontend-tools) name
those tools a set at a time, and an agent lists the sets it is meant to sit
beside under frontend_tools.
A set only names the tools. Their handlers come from the Reactor plugin that
draws the page — each declares its tools in its AgentTools bundle, and they
run through the reactor's command registry on what the person sees — never
from the spec. When the page is not shown, the tool says so — the Cells tools
answer that no grid is shown — and the agent asks for it first.
Fields
| Field | Meaning |
|---|---|
id, version, name, description | As on every spec. |
toolset | The tools of the set, by the name the plugin registers them under. |
enabled | Whether the set is offered, true unless said. |
tags | Words to find it by. |
icon, emoji | Its marks: icon is <package>:<name>, the package @datalayer/icons-react or @primer/octicons-react (see MCP servers); emoji is drawn where there is no icon. |
# frontend-tools/cells.yaml
id: cells
version: 0.0.1
name: Cells
description: Read and write the spreadsheet on the person's screen, and chart it — the grid drawn by Datalayer Cells.
tags: [frontend, cells, spreadsheets]
enabled: true
# Data: the values of a range, read or written. Charts: insert one over a
# range, list them. Screen: select a range to show the person.
toolset:
- cells_read_range
- cells_write_range
- cells_insert_chart
- cells_list_charts
- cells_select_range
icon: "@primer/octicons-react:table"
emoji: "🧮"
The catalogue
| Set | Tools | What it does |
|---|---|---|
cells | 5 | Read and write the spreadsheet on the person's screen, and chart it — the grid drawn by Datalayer Cells. |
decks | 18 | Read, write and drive presentations kept as data — a deck, its slides, and the one on screen. |
jupyter-notebook | 3 | Interact with a Jupyter notebook. |
jupyter-notebook-read | 2 | Read a notebook without changing it — cells, outputs and errors. |
jupyter-notebook-propose | 4 | Read a notebook and propose changes for a person to accept, never applying them. |
jupyter-notebook-edit | 6 | Read and edit a notebook, and run cells — but never delete from it. |
lexical-document | 3 | Read and write the blocks of a Lexical document, run Jupyter cells in the page, and draw diagrams into the document with Excalidraw. |
The three notebook sets beside jupyter-notebook say how far an agent may go
in a notebook: jupyter-notebook-reproducer names jupyter-notebook-read,
and jupyter-cell-fixer names jupyter-notebook-propose, so its fixes wait
for the person to accept them.
An agent beside a spreadsheet
The Example Output Agent (agents/example-output.yaml) answers in one of six
output modes. Five are a block in the answer, which the page detects and draws;
the sixth works on the grid through the cells set:
| Mode | What the answer is |
|---|---|
TABLE | One GitHub-flavoured Markdown table. |
JSON | One fenced json block. |
CHART | One fenced json block whose first line is // chart, the rest an ECharts option. |
SPREADSHEET | One fenced csv block whose first line is # filename: <name>.csv, drawn with Datalayer Cells in the chat and in the side panel. |
FILE | One fenced block whose info string is a file extension, its first line # filename: <name.ext>. |
SHEET CHART | No block: asked to chart the spreadsheet shown, it calls cells_read_range to find the data and cells_insert_chart over it, then says which chart it inserted where. |
# agents/example-output.yaml
id: example-output
harness: pydantic-ai
backend_tools: []
frontend_tools:
- cells:0.0.1
disable_tool_approvals: true
suggestions:
- text: >-
Give me a spreadsheet of twelve months of sales by region (North,
South, Online), with a Month column, as one ```csv fenced block whose
first line is `# filename: sales.csv`.
summary: "Sales spreadsheet"
- text: >-
Chart the sales spreadsheet: a column chart of the three regions by
month, titled Sales by region, inserted on the grid below the data.
summary: "Chart the spreadsheet"
Backend tools and frontend tools
A tool that runs on the runtime, in Python, is a backend tool; a tool that runs on the page is a frontend tool. An agent may list both.