Agent tools
Every tool the canvas agent can call, with its real input schema.
Tools — 13
ToolWhat it does
describeDataThe data catalogue: every entity with its description, id keys, props and relations. Call this whenever you are not certain a prop or relation name exists.
lookAtCanvasWhat is on the board right now: one line per node with the handle you address it by, plus WHICH NODES THE USER HAS SELECTED. Call this first whenever the user says this/that/it, or before you edit, connect, group or remove anything you did not just create.
showRecordPut one row of one entity on the board as a card. The row is looked up first: a miss comes back as an error listing real values, so never guess an identifier twice.
showRelatedFollow a relation off a record card and put what it points at beside it, linked. Use this for 'and his computer', 'the project's tasks' — never look the related row up by hand, the relation value is an identifier, not a name.
listRecordsAdd a NEW table of an entity's rows, optionally sorted and capped. Use it for 'show me all / list the…'. To re-sort or re-column a table already on the board, use `edit`.
chartAdd a NEW chart: group one entity's rows by a prop and plot a metric. Prefer it over a table for 'how many', 'per', 'by', 'distribution', 'average', 'total' and 'trend'. To change a chart that is already on the board — its shape, its grouping, its metric — use `edit`, never this.
noteLeave a note — a caveat, a conclusion, something the user asked you to write down. With `on`, it is pinned to that node (and travels with it); without, it is a free-standing sticky on the board.
editChange something already on the board in place: a chart's shape or grouping or metric, a table's columns or sort, a title, a note's text. This is ALWAYS the right tool for 'make this a pie', 'sort it by x', 'rename it' — adding a replacement instead would throw away where the user put the node and what it is linked to. Only send the fields you want changed.
connectDraw a link between two nodes that are already on the board, to say they belong together.
removeTake nodes off the board, with every link touching them.
groupWrap nodes in a titled block so they read as one thing. The user can then save that block and reuse it in another report.
tidyLay the whole board out again in neat rows. Use it when the board has grown messy, not after every addition.
clearTake everything off the board. Destructive — only when the user asks to start over.
Input schemas
Scripted turn
The offline exercise of the canvas SDK: 8 steps through the same buildNode / applyChanges path a tool call takes, with no API key and no model. It runs as one Convex mutation (canvas.runDemo) against the report you were last in.
0clear— start from an empty board
1add— the looked-up row path — a miss would come back as an error
{"kind":"entity","entityName":"Customer","identifiers":[{"key":"email","value":"robert.johnson@example.com"}],"propsToDisplay":["name","role","region","computer"]}2add— the customer's machine, linked to it
{"kind":"entity","entityName":"Computer","identifiers":[{"key":"id","value":"COMP003"}]}3add
{"kind":"chart","title":"Products per category","entityName":"Product","groupBy":"category","metric":{"op":"count"},"chartType":"bar"}4add
{"kind":"entityList","entityName":"Task","propsToDisplay":["id","title","status","completion"],"sort":{"field":"completion","direction":"desc"},"limit":5}5add
{"kind":"note","subject":"Review the budget","body":"Mobile App Development is at 65% with $150k allocated."}6add
{"kind":"query","label":"Completed tasks","text":"list Task where status = Completed"}7tidy