Grasshopper AI: Teaching Visual Programs to Describe Themselves

We have recently been experimenting with Grasshopper and AI with one question in mind: how do you turn a Grasshopper definition into a tool that an LLM can actually call? Grasshopper already has the obvious-looking answer — clusters, its existing container for reusable logic — but clusters have a fundamental limitation. They don't know how to describe themselves. A designer looking at a Grasshopper cluster can hover over inputs, trace wires, and experiment with values until they understand what it does. An LLM can't do any of that. It needs a formal contract: what inputs exist, what types they expect, which are required, and what the outputs represent. Without that metadata, the model is flying blind.

Solving that matters more than it might sound. Twenty years of Grasshopper work has produced an enormous library of definitions encoding hard-won domain knowledge: structural logic, fabrication constraints, parametric façade systems, and environmental analysis routines. No LLM can re-derive that from first principles, and no designer should have to throw it away to work with one. If we want AI to empower computational designers rather than replace them, we need a way to lift what already exists into a form the AI can use.

The Schema as Contract

Helpfully, the AI side of this is already solved. Every major LLM API uses the same convention (MCP) for tool definitions: a JSON schema describing inputs, types, and outputs. The question isn't what interface to invent, it's how a visual program reaches the interface that already exists.

The answer is to wrap any cluster with a declarative boundary: input and output markers that carry explicit type information. They look like the cluster I/O components Grasshopper already ships, but with teeth. Instead of "this input accepts whatever you wire to it," the boundary says "this input is a 3D point," or "this input is a number representing a radius," or "this input is optional and defaults to 10."

Once those boundaries are defined, the cluster can compile itself into a JSON schema — exactly the format the LLM expects. The visual logic inside is untouched; only the interface is formalised.

Execution Without Side Effects

So we have a cluster that an LLM can understand and choose from a library of many, but then we need it to be able to execute it. You can't just solve the cluster in place when the AI calls it. Grasshopper's solver is stateful and global; running it in isolation is rarely what is desired. The power of Grasshopper comes from chaining together multiple units of computation.

What we needed was a component that could take these JSON cluster schemas, along with input definitions, and execute them within the native solver process in Grasshopper. So when the AI invokes a tool, the runtime duplicates the cluster's contents into an isolated context, injects the inputs, solves there, extracts the outputs, and discards the duplicate. The original definition never moves.

Put more simply: we are manipulating Grasshopper definitions so that they can be called by an LLM, but remain fully inside of Grasshopper. The LLM only sees a JSON Schema and Grasshopper only sees a Grasshopper Cluster.

What This Pattern Enables

Discoverability. The schema clusters carry the additional information the AI needs to reason about them, so they can be indexed and searched semantically. The AI isn't limited to a fixed toolkit handed to it at the start of a session — it can pull from a growing ecosystem and find the right tool for the task.

Composability. Because every input and output is typed with rich information and descriptions, the AI can chain clusters together, passing the output of one into the input of another with confidence that the connection is valid. It's type-safe pipelining for design operations.

Agent Collaboration. It enables greater collaboration with LLMs by letting them hand off deterministic execution to a tool that a designer can create — the AI decides what to run and when, while the cluster guarantees exactly how.

Portability. Self-describing clusters export as standalone files that work anywhere the runtime exists. A cluster built by one designer becomes a tool available to anyone running the system.

Each of these is its own unlock, but they compound. A designer keeps building clusters the way they always have. On export, each one automatically becomes a callable AI capability. The twenty years of work doesn't get rewritten — it gets a new interface.

The animation below shows an example JSON Cluster Schema with a simple Create Circle component inside the cluster. This is then plugged into an execution node with a JSON input that defines the radius as 10. Note that none of this uses any AI LLMs, but it was a prerequisite to our AI experiments. Whilst it is not the most glamorous demonstration, what it unlocks — any Grasshopper definition becoming an MCP tool — is certainly a worthwhile experiment.

The walkthrough below runs the whole pattern end to end on a slightly more complex example: a cluster that takes a Brep tower massing and splits it into floor plate slabs. We wrap it in a typed schema boundary, compile it to JSON, and hand that schema — together with a JSON input carrying the massing geometry and a few numeric parameters — to an execution node that duplicates the cluster, solves it in isolation, and reads the generated slabs back. The logic inside is ordinary Grasshopper; only the interface is formalised. Watch a piece of visual logic hand the AI its own contract.

No LLM runs anywhere in this clip. Everything you see is the runtime the AI experiments are built on — the plumbing that lets any Grasshopper definition describe itself as an MCP tool and execute on demand.