Trialbook

Inspiration

Interactive simulations are how a lot of students first meet physics; PhET alone reports hundreds of millions of simulation runs a year. But a simulation is a solitary tool. The part of real science a slider cannot do, running the same experiment thirty times while changing one thing and then fitting a law to the numbers, is exactly what an agent is good at. And teachers now face a second problem: how do students use AI in a lab without the AI doing the lab?

WebMCP answered both at once. A lab is a small set of well-typed actions with a human watching: set parameters, run, sweep, repeat, optimise, plot, fit, write. That is precisely the shape a WebMCP tool wants. An agent that scrapes the screen cannot drag a slider eight times, read eight numbers off a canvas and fit a curve to them. With tools it calls sweep_parameter once, gets eight measurements back as JSON in about four seconds, calls fit_model, and gets period_s = 2.021·length^0.5 with R² = 1.000. Tools also give the page a way to say no: a screen-scraping agent cannot be refused, but a tool can, and Trialbook uses that to keep the student in charge.

What it does

Trialbook is a physics and biology lab in the browser with four experiments: projectile motion, a pendulum, predator–prey populations, and an RC circuit. You move sliders and watch the simulation. Your agent, working through fourteen WebMCP tools on the same page, runs trials and sweeps, fits laws, finds optima, quantifies uncertainty, and writes in the shared lab notebook under its own name.

What people and agents can now do together that was difficult or impossible before:

• Discover a law in one conversation. "Sweep the length from 0.25 to 4 m in 8 steps, fit a power law to the period, and record what it means" comes back as a chart with the dashed fitted curve, the equation, and a notebook entry: exponent 0.50, R² 1.000, the period grows with the square root of the length. Least squares on the page, not the model's arithmetic.
• Find an optimum properly. optimize_parameter runs a golden-section search. Under heavy drag it found the best launch angle, 39.08°, to a 0.08° bracket in 19 trials. By hand that is an afternoon of slider-dragging.
• Put an uncertainty on a number. With simulated measurement error on, "repeat the current trial ten times" comes back as 41.61 ± 0.08 m (mean ± standard error), with error bars on the chart.
• Use AI in a lab without the AI doing the lab. Assignment mode turns the agent into a lab partner: it cannot run a sweep until the student has written a hypothesis, and every agent conclusion arrives as a proposal the student accepts, edits or rejects. The exported report has a "who did what" table with those counts.
• Keep one notebook with two authors. Hypotheses, observations and conclusions from both sides, each stamped with the experiment and the parameters in force at the time.

How it creates a better experience. Before, a student who wanted to know whether the pendulum period depends on release angle dragged one slider twelve times and copied numbers into a spreadsheet. Now they ask, watch the sweep run on the stage with a progress bar and a cancel button, see the chart appear with its fitted curve, and read the conclusion in the notebook with the settings it came from. About a minute in ChatGPT's built-in browser, end to end. The person never loses the wheel: move a slider mid-conversation and the agent's next get_lab_state reads "you: set gravity to 1.59 m/s²"; ask "what did I change?" and it names the change, predicts the effect and runs a trial to check (range 41.5 m on Earth became 82.5 m at lunar gravity). Agent changes glow purple on the sliders and arrive as toasts; yours are blue. Anything the agent wrote can be edited or deleted.

Live: https://minewefu.github.io/trialbook/ · Source: https://github.com/minewefu/trialbook (MIT)

How we built it

React, TypeScript and Vite, deployed to GitHub Pages; no backend. The physics engines are plain functions: a closed-form projectile with a semi-implicit Euler integrator when drag is on, fourth-order Runge–Kutta for the nonlinear pendulum and for Lotka–Volterra, and the exact first-order solution for the RC circuit.

How WebMCP is implemented:

• Every tool is registered with document.modelContext.registerTool through one 150-line wrapper. It feature-detects the API, keeps a local registry that powers an in-page Tools panel (anyone can run any tool without an agent, through the same code path), clamps outputs, and turns thrown errors into { ok: false, error, hint } the model can act on.
• Fourteen tools: eight lab-wide (get_lab_state, open_experiment, get_results, plot_results, fit_model, notebook_add_entry, notebook_read, export_report) and six per experiment (set_parameters, run_trial, sweep_parameter, run_repeats, optimize_parameter, reset_experiment). The experiment group is registered when an experiment opens and replaced when another opens, so the schema always describes the current sliders; the handlers act on whichever experiment is open, so a cached schema still behaves.
• readOnlyHint on every reading tool; untrustedContentHint on notebook_read, the one tool that returns text people typed.
• The execution AbortSignal is wired into sweeps, repeats and optimisations: cancelling from the agent or the on-page button stops the loop and returns the partial results with cancelled: true.
• Validation is strict and specific: angle = 120 is outside the allowed range 0 to 90 deg; Unknown parameter "mass". Valid parameters: speed, angle, …. In assignment mode the refusal says exactly what to ask the person for.
• Outputs stay under about 1.4K characters: results are paged, sweep summaries shrink to fit, and the lab state drops detail in tiers rather than truncating mid-JSON.
• 66 unit tests cover the physics (projectile within 0.5% of the closed form, pendulum within 0.5% of the exact elliptic-integral period, the Lotka–Volterra invariant conserved, RC time constant equal to R·C), the fits, the tools' output sizes, cancellation and assignment mode. The tools reference is generated from the tool definitions by a test that fails if it drifts.
• Verified end to end in ChatGPT's built-in browser (GPT-5.6 Sol, Windows desktop app) and in Chrome 151 with the WebMCP flags.

Challenges we ran into

• The output budget. Chrome's guidance asks for tool outputs around 1.5K characters, and a seven-parameter experiment with seven measurements blows through that fast. The fix was structural: paged results, sweep summaries that shrink row by row until they fit, and a lab-state snapshot that drops detail in tiers, so the agent always gets valid JSON rather than a truncated one.
• Conclusions that stayed in chat. In the first live test the agent answered "the exponent is 0.50" in the conversation and never wrote it into the notebook, which made assignment mode pointless. Every batch result now ends by asking for the conclusion to be recorded, and in assignment mode a chat-only conclusion does not count.
• Tool groups that change under the agent. Switching experiments swaps six tools. If the client caches the old schema, the calls still have to work, so handlers act on whichever experiment is open and validate against it, and the schema is only a description.
• Layout. The first version spent its pixels vertically. Two rounds of screenshots later, parameters sit under the stage in fixed-width rows, tools are a chip cloud, and the readouts follow the cursor without jumping.

Accomplishments that we're proud of

The whole loop works from a plain conversation in ChatGPT's browser: sweep, fit, propose, accept, report, with numbers that match the physics to the last digit. The agent asked for a hypothesis before it would sweep, and its conclusion showed up as a proposal with Accept, Edit and Reject buttons, exactly as designed. And the physics is honest: every engine is tested against an exact solution.

What we learned

Tools are a better place for policy than prompts. Putting "write a hypothesis first" into a tool's refusal message, rather than hoping the model remembers, made the behaviour reliable. Small, well-described tools with strict errors let the model self-correct in one turn. And a specific "what changed since you last looked" feed is worth more than any amount of state dumping, because it tells the agent what the person cares about right now.

What's next for Trialbook

Real data import, so a student can compare their own pendulum timings against the model. More experiments, chosen for the laws they let you discover. A teacher view of the attribution report across a class. And, as WebMCP clients mature, declarative tools for the notebook form so the lab works in more browsers.

Built With

• canvas
• react
• typescript
• vite
• vitest
• webmcp
• zustand