Tools reference¶

These are the tools your AI assistant sees. Look-only tools never change anything. Edit tools change the open Designer, and each change waits for you to press Save.

Look-only tools¶

Always available, even while Enable edits is off.

Tool	What it does
`designer_status`	Module version, whether edits are enabled, the key's bound user and project grants, and that user's open Designers with their Claude switch and self-test results. Call it first.
`designer_ping`	Sends a no-op command to one Designer and returns how long the round trip took.
`view_read`	Reads a view.
`component_types`	Lists the Perspective component types the user's Designer knows (id, name, palette category, default name). Optional `category` filter; deprecated types are hidden unless `includeDeprecated` is true.
`component_schema`	The props JSON schema, default props, events and extension functions of one component type.
`canvas_screenshot`	Takes a screenshot of the Designer canvas.

Edit tools¶

An edit tool works only when all three are true:

An administrator has turned on Enable edits (see Configure).
The key is granted the project.
The user has switched Claude ON in that Designer.

Tool	What it does
`view_open`	Opens a view in the user's Designer, or brings it to the front. Needed before `view_read` or `view_apply` on a view that is not open. Returns the live revision.
`view_create`	Creates a new view with a root container (`ia.container.flex` by default), opens it and returns its revision. Unsaved until the user presses Save. Refused with `view_exists` if the path is taken. A view still opening when the relay timeout nears returns `unconfirmed`: it exists, so read it rather than creating it again.
`view_apply`	Applies a batch of changes to a view (see view_apply operations).
`view_select`	Selects components (name paths or index paths) on an open view so the user sees what the assistant means; an empty list clears the selection.

view_apply operations¶

view_apply carries ten kinds of operation. Each one is one undo step in your Designer.

Set properties
Set bindings
Set events
Set component scripts: message handlers, custom methods and extension functions
Set property-change scripts
Add a component
Delete a component
Wrap components
Replace a component in place
Reorder components

Adding a component at a position other than the end takes two undo steps: the add, then the move into place.

If you change a component the batch touches after the assistant last read the view, the batch is refused as stale. The assistant then reads the view again and rebuilds the batch.

Report tools¶

Report tools need the Reporting module. A Designer without it loads normally and switches only the report features off.

Tool	Kind	What it does
`report_read`	Look-only	Reads a report.
`report_preview`	Look-only	Renders report pages from the Designer's sample data, as PNG images on a white background.
`report_open`	Edit	Opens a report in the user's Designer, or brings it to the front. Needed before `report_apply`, `report_set_data` or `report_preview` on a report that is not open. Returns the live revision.
`report_create`	Edit	Creates a report with one empty page (612 by 792 points by default) and opens it. Refused with `report_exists` if the path is taken. A report still opening when the relay timeout nears returns `unconfirmed`: read it rather than creating it again.
`report_apply`	Edit	Changes the layout: sets, deletes and reorders shapes, written in the report's own XML. Each change is one undo step.
`report_set_data`	Edit	Sets parameters and SQL, named query or script data sources. Not undoable: it clears the report's undo history and returns the previous configuration.

Executing content¶

View bindings that query, script or write tags, property-change scripts, and scripted report charts can run before you save. The module refuses them unless an administrator turns on Allow executing content (off by default).

view_apply and report_apply are marked as destructive tools.

Start-up self-tests¶

Each Designer tests the Perspective features these tools rely on when it starts. With the Reporting module, it runs three more: report-layout, report-data and report-preview. When a test fails, only that feature switches off and its tools are refused as feature_off, with the reason. The results show in the Claude panel and in designer_status.