interactive-graphing

---
name: interactive-graphing
description: Show and keep editing interactive math graphs inline in the conversation with the Graph Integration connector (create_graph, add_objects, update_objects, remove_objects, set_viewport, edit_graph, analyze_graph, get_graph_state, show_graph). Use it instead of a general chart or visualization tool whenever a function, equation, derivative, tangent, intersection, transformation, area, piecewise/parametric/polar curve or set of points would be clearer as a picture, and whenever the user refers to a graph already in the conversation ("add its derivative", "make the new line dashed", "move that point", "zoom in near the intersection", "remove everything except the parabola").
---

# Interactive graphing

The Graph Integration connector draws real, interactive graphs (pan, zoom, hover, toggles, draggable points, sliders) inline in the chat. For any math graph, use its tools rather than a general chart or visualization tool: those draw static pictures without equal axis scales, symbolic derivatives or a graph you can keep editing. A graph is a **persistent object** with a stable `graph_id`: you create it once and then edit that same graph for the rest of the topic. The server owns the canonical state; every tool result contains the complete current state, so you never need to remember what is on the graph from older messages.

## When to graph

Graph when a picture materially helps the explanation:

- shapes and behaviour of functions, comparing several functions
- solving equations or systems graphically (intersections, roots)
- derivatives, tangent and secant lines, extrema, concavity, limits and asymptotes
- areas and definite integrals (shaded regions)
- transformations and families of curves (use a `parameter` slider)
- piecewise, parametric, polar and implicit curves (circles, conics)
- plotting given data points

Do not graph pure arithmetic, symbolic algebra the user only wants written out, or when the user asks for text only. If the user explicitly asks for a graph, always make one.

## Keep the graph clean (Desmos-style)

Draw **only what the user asked for**. The graph behaves like Desmos: the user clicks a curve to see its roots, extrema, intercepts and intersections as gray dots, and clicks any dot or point to read its coordinates. So:

- Do not add points for roots, vertices, intercepts or intersections, helper lines (axes of symmetry, asymptote lines, guides), labels or shaded regions unless the user asks for them, or they are the point of the question ("mark the vertex", "show the asymptotes").
- Answer questions about such points in your reply (use `analyze_graph` for the numbers) and mention that the user can click the curve to see them on the graph.
- When the user does ask for a point, add just the point. Put its name in `label`, which appears in the legend. Don't set `show_label` or `show_coordinates` unless they ask for text on the graph.
- Prefer one clear object per idea; never duplicate information as both a point and a label.

## Core workflow

1. **First graph of a topic:** call `create_graph` with every object the explanation needs in one call. Give functions you will talk about a `label` such as `"f(x)"` (then a derivative of it shows as f′(x) in the legend). Usually omit `viewport`: the server frames roots, extrema, intersections and points automatically. Pass one when you know better (see Viewports).
2. **Every follow-up about the same topic edits the same graph.** Use the `graph_id` and `base_revision` from the latest tool result:
   - new things → `add_objects`
   - change an existing thing (expression, position, style, label) → `update_objects` with only the changed fields; keep its id
   - delete → `remove_objects` (`ids`, or `keep_only` for "remove everything except …")
   - move the view → `set_viewport`
   - several kinds of change for one request → one `edit_graph` call
3. **One call per user request.** Each call renders a fresh copy of the graph in the chat (older copies become read-only snapshots), so batch everything a request needs into a single call.
4. **Explain the change** in one to three sentences: what changed and what it means mathematically. Refer to objects the way the user sees them (color, label, "the dashed line"), not by internal id unless the user uses ids.

Never create a new graph just to add, change or remove something; never remove and re-add an object to change it (that breaks its id and everything that depends on it).

## Keeping track of state

- The latest tool result lists every object: id, definition, style, the revision it was created/edited at, and the current view. Treat it as the truth.
- The user can change the graph themselves (pan/zoom, hide curves, drag points, move sliders). Those edits are saved to the same graph and you may receive a context note about them. **Call `get_graph_state` before a context-dependent edit** when:
  - the latest graph result is not in recent context (long conversation, or it was summarized),
  - the user mentions something they did on the graph ("I moved the point", "where I zoomed"),
  - an edit was rejected as stale.
- Always pass `base_revision`. If an edit is rejected as stale, the message shows what changed; re-read the state, decide whether the edit still makes sense, and retry with the new revision. Do not blindly overwrite the user's change.

## Resolving references

Map the user's words to object ids from the current state:

| User says | Usually means |
|---|---|
| "it", "its", "the function" | the curve discussed in the previous turn; otherwise the most recently created or edited explicit curve |
| "the new line/curve/point" | the most recently created object of that kind (highest created revision) |
| "the parabola", "the line", "the sine curve" | the object whose expression has that shape |
| "f", "g", "f(x)" | the object with that label |
| "that point", "the point" | the most recently mentioned or added point |
| "the derivative" | the derivative object (or add one if none exists and the user asks to show it) |
| "the original parabola" | the earliest-created matching object |

If two or more objects fit equally well and the action changes or removes something, **ask a short clarifying question** naming the candidates by expression or color (for example: "Do you mean the blue parabola y = x² − 4 or the orange one y = (x − 1)²?"). For harmless actions like zooming, pick the most plausible and say which you chose.

## Viewports

- By default leave the view alone: the server keeps the user's current zoom/pan through edits, and only widens it if new objects would be entirely off-screen.
- Set it when the user asks ("zoom in", "show x from 0 to 10") or the topic needs a specific window.
- "Zoom near X": find the coordinates first with `analyze_graph` (intersections, roots, extrema), then `set_viewport` with `center` and a `width`/`height` a few units wide (or roughly a quarter of the current size).
- Like Desmos, one unit has the same length on both axes, so a requested window is widened in one direction to fill the view (the view is about 1.6 times wider than tall). Pick windows with that in mind. Only set axes `aspect: "free"` for data whose x and y scales differ hugely (e.g. years vs. millions).
- Good starting windows: trigonometry x ∈ [−2π, 2π] with axes `x_ticks: "pi"`; growth/decay start the y-range near 0.
- `fit: "all"` or `fit: [ids]` frames objects automatically.

## Mathematical honesty

- **Derivatives:** add a `derivative` object; the server differentiates symbolically and returns the expression. Report that expression; do not substitute your own. Tangents, secants and points on curves are computed from the actual function too.
- **Numbers:** use `analyze_graph` for roots, intersections, extrema, values, slopes and definite integrals instead of estimating from the picture. Quote numerical results to sensible precision; give exact forms (like 1 ± √6) only when you derived them and they agree with the numerical result.
- If a tool result disagrees with your reasoning, trust the tool, re-check your work, and say so.
- Expressions are real-valued and in radians: `ln(x)` is the natural log (`log(x)` also means ln; prefer `ln`), `log10(x)` base 10, `log(x, b)` base b. Odd roots of negatives are real (`x^(1/3)` at −8 is −2). Syntax details: `references/expression-syntax.md`.
- Never quietly change what the user asked to plot. If an expression is rejected, fix only the syntax (`|x|` → `abs(x)`, `sin x` → `sin(x)`); if the intent is unclear, ask.
- If something cannot be done reliably (symbolic antiderivatives, complex-valued functions, 3D, inequalities in x and y beyond the supported region shading), say so plainly and offer the closest supported alternative (e.g. a numerical definite integral with a shaded region, or `method: "numeric"` for the derivative of `floor`, `sign`, `mod`).

## Objects at a glance

`function` (expr in x, optional domain) · `piecewise` · `derivative` (of, order, method) · `tangent` (of, x; draggable) · `secant` (of, x1, x2) · `point` (x, y, or `on` a curve; draggable) · `points` (coordinates, connect) · `line` (through / point+slope / x / y; segment, ray) · `label` · `region` (top/bottom bounds, x range; reports the integral) · `parametric` · `polar` · `implicit` (equation in x and y) · `parameter` (slider usable in any expression).

Full field reference with examples: `references/object-reference.md`. Worked multi-turn conversations, including every common follow-up phrasing: `references/conversation-patterns.md`.

## Style conventions

- Let colors auto-assign; they stay distinct and readable in light and dark mode. Use `line_style: "dashed"` and `color: "gray"` for asymptotes, guides and auxiliary lines.
- Make points draggable (`draggable: true`) and tangents draggable (default) when exploring helps; use sliders (`parameter`) for "what happens when a changes".
- Mention interactivity once when it is useful ("click the curve to see its roots and vertex", "drag the point along the curve", "use the slider for a").

## Clients without inline rendering

Some clients (for example Claude Code) run the tools but do not display MCP Apps. The tool results still contain the full state as text; describe the graph and the results in words there.

• SKILL.md 10 KB
• references/conversation-patterns.md 5 KB
• references/expression-syntax.md 1 KB
• references/object-reference.md 5 KB