Tool Reference

Every tool is typed: inputs are validated against the official Etch public API schemas and results come back as structured content your harness can rely on. The Effect column is the key to the editing model:

• read - never changes anything.
• buffered - lands in the open builder document; saved only by an explicit etch_save_document.
• persist - written to the database immediately.
• session - changes agent-side session state (which target is selected), nothing in WordPress.

81 tools as of 2.1.0.

Targets, status, and navigation

Tool	Effect	What it does
etch_list_targets	read	List connected Etch targets and the current working target.
etch_select_target	session	Select the working target for future tools.
etch_get_status	read	Etch availability and runtime status, including unsaved changes.
etch_get_navigation_context	read	Active document identity and builder navigation context.
etch_list_posts	read	List posts visible from the target, optionally by post type.
etch_list_templates	read	List templates visible from the target.
etch_open_post	buffered	Switch the target to a post; refused while changes are unsaved.
etch_open_template	buffered	Switch the target to a template; refused while changes are unsaved.
etch_go_to	session	Navigate the builder to a supported UI area.
etch_get_color_scheme	read	Read the builder color scheme.
etch_set_color_scheme	persist	Set the builder color scheme.

Reading the document

Tool	Effect	What it does
etch_get_document_tree	read	The current document's full block tree.
etch_get_block_json	read	One block's full JSON payload.
etch_get_selected_block	read	The block currently selected in the builder.
etch_find_blocks	read	Find block ids by a typed predicate.

Editing blocks

Tool	Effect	What it does
etch_insert_blocks	buffered	Insert validated blocks.
etch_replace_block	buffered	Replace one block.
etch_update_block	buffered	Patch one block (attributes, text, classes).
etch_mutate_block_attributes	buffered	Granular attribute and class changes on one block.
etch_duplicate_block	buffered	Deep-copy one block.
etch_move_block	buffered	Move one block within the document.
etch_delete_block	buffered	Delete one block.
etch_copy_block	read	Copy one block into an opaque portable payload.
etch_paste_block	buffered	Paste a copied payload anywhere in the document.

Saving and history

Tool	Effect	What it does
etch_save_document	persist	Explicitly save the active document. Always user-approved.
etch_undo	buffered	Undo the last document operation; repeatable.
etch_redo	buffered	Redo the last undone operation.

Buffered styles

Tool	Effect	What it does
etch_list_styles	read	Buffered style rules and CSS variables.
etch_apply_style_patch	buffered	Apply validated rules and CSS variables without saving.
etch_delete_style	buffered	Delete one buffered style rule.
etch_get_style_variable	read	Read one global CSS variable.
etch_remove_style_variable	buffered	Remove one buffered CSS variable.

Global stylesheets

Tool	Effect	What it does
etch_list_stylesheets	read	List global stylesheets, optionally including CSS.
etch_get_stylesheet	read	Read one global stylesheet.
etch_create_stylesheet	persist	Create a global stylesheet.
etch_update_stylesheet	persist	Update a global stylesheet.
etch_append_stylesheet	persist	Append CSS to a global stylesheet.
etch_delete_stylesheet	persist	Delete a global stylesheet.
etch_list_custom_media	read	List global @custom-media definitions.
etch_add_custom_media	persist	Add an @custom-media definition.

Components

Tool	Effect	What it does
etch_list_components	read	Component summaries, optionally filtered.
etch_get_component_json	read	One component including its block tree.
etch_upsert_agent_component	persist	Create or update a component by key.
etch_delete_agent_component	persist	Delete components by key.
etch_enter_component_edit_mode	session	Focus a component for direct editing of its tree.
etch_save_component_edit_mode	persist	Persist the focused component.
etch_exit_component_edit_mode	session	Leave focus mode, optionally reverting.
etch_is_in_component_edit_mode	read	Whether focus mode is active.

Loops

Tool	Effect	What it does
etch_list_loops	read	List buffered loop definitions.
etch_upsert_loop	buffered	Create or replace a loop by key.
etch_delete_loop	buffered	Delete a loop by id.
etch_bind_loop_to_block	buffered	Bind a loop definition to a loop block.

Custom fields

Tool	Effect	What it does
etch_list_field_groups	read	List all custom field groups.
etch_get_field_group	read	Read one field group by id.
etch_create_field_group	persist	Create a field group.
etch_update_field_group	persist	Replace a field group.
etch_delete_field_group	persist	Delete a field group.
etch_add_field	persist	Add a field to a group.
etch_update_field	persist	Replace a field in a group.
etch_remove_field	persist	Remove a field from a group.
etch_get_field_values	read	All resolved field values for a post.
etch_get_field_value	read	One resolved field value for a post.
etch_set_field_value	persist	Set one field value.
etch_set_field_values	persist	Set several field values at once.
etch_delete_field_value	persist	Clear one field value.

ACSS

Tool	Effect	What it does
etch_detect_acss	read	Detect Automatic.css and sample its live variables in the builder tab.

Skills

Tool	Effect	What it does
etch_list_skills	read	List core, user, and runtime skills.
etch_get_skill	read	Read one skill by name and provider.
etch_get_skill_reference	read	Read a declared reference file for a skill.
etch_list_local_skills	read	List local core and user skills.
etch_create_local_skill	persist	Create a user skill.
etch_update_local_skill	persist	Update a user skill.
etch_validate_local_skills	read	Validate locally authored user skills.
etch_create_skill_reference	persist	Create or overwrite a reference file for a local skill.

Project Memory

Tool	Effect	What it does
etch_recall_project_memory	read	Recall the Project Digest and record brief. Always first.
etch_inspect_project_memory	read	Audit stored memory per project.
etch_remember_project_memory	persist	Store one confirmed Decision, Observation, or Reference.
etch_correct_project_memory	persist	Correct one record's payload under an expected revision.
etch_forget_project_memory	persist	Delete one record or a confirmed aggregate.
etch_write_project_digest	persist	Write the narrative Project Digest.
etch_recover_project_memory	persist	Explicit URL rebind, or quarantine a corrupt store.