Skip to main content

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.

ToolWhat it does
gh_get_selectedReads only the components currently selected on your canvas. Used whenever you ask about "this component" or "the selected components".
gh_get_errorsReads only components that have runtime errors, along with their error messages. Used when debugging broken definitions.
gh_get_by_guidReads specific components by their instance GUIDs (for example, to inspect a component found in an earlier step).
gh_getReads 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_reportGenerates 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.
Keeping context small

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:

ToolWhat it does
gh_list_categoriesLists all component categories (tabs) available in your Grasshopper installation (such as Maths, Curve, Surface, Mesh, or installed third-party plugins).
gh_list_componentsSearches 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:

ToolWhat it does
gh_document_listLists all Grasshopper documents currently open in the editor and indicates which one is active.
gh_document_switchSwitches the active Grasshopper canvas to another open document.
gh_document_newCreates and activates a new blank Grasshopper document.
gh_document_openOpens a .gh or .ghx file from disk in Grasshopper.
gh_document_saveSaves the active Grasshopper document (to its current file path or a new path).