Canvas Tools — Read
These tools let the assistant (and external MCP clients) inspect your Grasshopper definition, find errors, discover what components are installed on your machine, and manage open .gh documents — without modifying your canvas.
Inspecting the active Grasshopper definition
When you ask the assistant about your definition, it reads the canvas as GhJSON using the tools below. Rather than reading the entire file every time, the assistant uses focused queries so responses stay fast and token-efficient.
| Tool | What it does |
|---|---|
gh_get_selected | Reads only the components currently selected on your canvas. Used whenever you ask about "this component" or "the selected components". |
gh_get_errors | Reads only components that have runtime errors, along with their error messages. Used when debugging broken definitions. |
gh_get_by_guid | Reads specific components by their instance GUIDs (for example, to inspect a component found in an earlier step). |
gh_get | Reads the current Grasshopper document with flexible filters: component state (selected, error, warning, enabled, disabled, previewon, previewoff), node role (params, components, startnodes, endnodes, middlenodes, isolatednodes), category, name, viewport visibility (viewportOnly), live output values (includeRuntimeData), and upstream/downstream wire hops (connectionDepth, such as "-2" for two upstream layers or "+1" for immediate downstream targets). |
gh_report | Generates a structured Markdown status report of the active file — component and wire counts, graph topology, groups, scribbles, viewport contents, file metadata, and runtime warnings or errors — with an optional AI summary. |
Reading live parameter values (includeRuntimeData: true) or exporting an entire large canvas uses significantly more tokens than reading only selected or errored components. Selecting the components you want help with before asking the assistant is the easiest way to keep conversations fast and inexpensive.
Discovering installed Grasshopper components
Before the AI generates a new definition, it can check which component categories and plugins are actually installed in your Grasshopper environment:
| Tool | What it does |
|---|---|
gh_list_categories | Lists all component categories (tabs) available in your Grasshopper installation (such as Maths, Curve, Surface, Mesh, or installed third-party plugins). |
gh_list_components | Searches installed components by category or name and returns their exact names, nicknames, descriptions, and input/output parameters. |
Managing Grasshopper documents
These tools inspect or manage open .gh / .ghx files in Grasshopper:
| Tool | What it does |
|---|---|
gh_document_list | Lists all Grasshopper documents currently open in the editor and indicates which one is active. |
gh_document_switch | Switches the active Grasshopper canvas to another open document. |
gh_document_new | Creates and activates a new blank Grasshopper document. |
gh_document_open | Opens a .gh or .ghx file from disk in Grasshopper. |
gh_document_save | Saves the active Grasshopper document (to its current file path or a new path). |