# Tool Reference

> All 81 etch-agent MCP tools as of 2.1.0, grouped by area with their effect class.

# 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. |