# Tool Catalogue

123 tools across 18 groups. Each tool requires a specific scope declared in `ToolHandlers.php`.

---

## Post Tools — scope: `read` / `write`

| Tool | Description |
|---|---|
| `get_post` | Get single post by ID (any post type) |
| `list_posts` | List posts with filters: status, type, search, paged |
| `create_post` | Create new post (any CPT), returns post_id |
| `update_post` | Update existing post: title, content, status, meta |
| `delete_post` | Delete or trash a post |
| `get_post_meta` | Get all meta for a post |
| `update_post_meta` | Set a single meta key value |
| `delete_post_meta` | Remove a meta key |
| `get_post_revisions` | List revision history |
| `restore_revision` | Restore post to a previous revision |
| `get_post_types` | List all registered public CPTs |
| `count_posts` | Count posts by status per type |

---

## Page Tools — scope: `read` / `write`

| Tool | Description |
|---|---|
| `get_page` | Get single page by ID |
| `list_pages` | List pages with search and parent filter |
| `create_page` | Create new page with optional template and meta |
| `update_page` | Update page title, content, status |
| `delete_page` | Delete or trash a page |

> **Note:** Never pass `page_template` to `wp_update_post()`. Set it via `update_post_meta($id, '_wp_page_template', 'slug')` after publish. See `docs/05-known-issues.md`.

---

## Media Tools — scope: `read` / `write`

| Tool | Description |
|---|---|
| `upload_media` | Upload file from URL to media library |
| `get_media` | Get single media item by ID |
| `list_media` | List media library with type/search filters |
| `update_media` | Update media alt, caption, title, description |
| `delete_media` | Delete media item permanently |
| `set_featured_image` | Set featured image on any post/page |

---

## User Tools — scope: `read` / `admin`

| Tool | Description |
|---|---|
| `list_users` | List users with role filter |
| `get_user` | Get user by ID |
| `create_user` | Create new user with role |
| `update_user` | Update user data |
| `delete_user` | Delete user |

---

## Comment Tools — scope: `read` / `write`

| Tool | Description |
|---|---|
| `list_comments` | List comments with status filter |
| `get_comments` | Get comments for a specific post |
| `get_pending_comments` | List all pending (awaiting moderation) comments |
| `approve_comment` | Approve a pending comment |
| `spam_comment` | Mark comment as spam |
| `trash_comment` | Move comment to trash |
| `delete_comment` | Permanently delete a comment |

---

## Menu Tools — scope: `read` / `write`

| Tool | Description |
|---|---|
| `get_menus` | List all navigation menus |
| `get_menu_items` | Get items in a specific menu |
| `create_menu_item` | Add item to a menu |
| `update_menu_item` | Update existing menu item |
| `delete_menu_item` | Remove item from menu |
| `reorder_menu_items` | Reorder menu items by passing ordered ID array |

---

## Taxonomy Tools — scope: `read` / `write`

| Tool | Description |
|---|---|
| `list_terms` | List terms in any taxonomy |
| `get_categories` | Get all categories |
| `get_tags` | Get all tags |
| `get_taxonomies` | List all registered public taxonomies |
| `create_term` | Create term in any taxonomy |
| `update_term` | Update existing term |
| `delete_term` | Delete a term |
| `add_post_terms` | Add/replace terms on a post |
| `get_term_meta` | Get term meta data |
| `update_term_meta` | Update term meta |
| `delete_term_meta` | Delete term meta |

---

## Option Tools — scope: `read` / `admin`

| Tool | Description |
|---|---|
| `get_option` | Get a WordPress option value |
| `update_option` | Update a WordPress option |
| `list_options` | List options matching a prefix |

---

## Site Tools — scope: `read` / `admin`

| Tool | Description |
|---|---|
| `get_site_info` | Site URL, name, description, WP version |
| `get_health` | Run WordPress site health checks |
| `get_active_theme` | Get active theme name, version, parent |
| `get_permalink_structure` | Get current permalink format |
| `update_permalink_structure` | Change permalink structure |
| `get_custom_css` | Get active theme custom CSS |
| `update_custom_css` | Replace active theme custom CSS |
| `get_theme_mods` | Get all customizer theme_mods |
| `update_theme_mod` | Update single theme_mod value |

---

## Plugin Tools — scope: `admin`

| Tool | Description |
|---|---|
| `list_plugins` | List all installed plugins with status |
| `get_plugins` | Alias for list with details |
| `activate_plugin` | Activate a plugin by slug |
| `deactivate_plugin` | Deactivate a plugin |

---

## Theme Tools — scope: `read` / `admin`

| Tool | Description |
|---|---|
| `list_themes` | List all installed themes |
| `get_themes` | Get installed themes with details |
| `switch_theme` | Activate a different theme |

---

## Theme Discovery Tools — scope: `read` (WoodMart + Elementor specific)

| Tool | Description |
|---|---|
| `theme_woodmart_elements` | List all WoodMart custom Elementor widgets |
| `theme_page_templates` | List all available page templates including Elementor Canvas/Full Width |
| `theme_taxonomies` | List all custom taxonomies registered by theme/plugins |
| `theme_custom_post_types` | List all CPTs registered by theme/plugins |
| `theme_widget_areas` | List all registered sidebar/widget areas |
| `theme_elementor_support` | Check Elementor feature support (full-width, canvas, etc.) |
| `theme_elementor_tokens` | Get Elementor kit design tokens: global colors, typography presets |

---

## SEO Tools — scope: `read` / `write` (Yoast + RankMath)

| Tool | Description |
|---|---|
| `get_seo_meta` | Get SEO fields for a post (title, description, focus keyword, robots) |
| `update_seo_meta` | Update SEO fields on a post |
| `get_post_seo_meta` | Alias for get_seo_meta |
| `update_post_seo_meta` | Alias for update_seo_meta |

---

## WooCommerce Tools — scope: `woo`

| Tool | Description |
|---|---|
| `wc_list_products` | List products with filters |
| `wc_get_product` | Get single product by ID |
| `wc_create_product` | Create a new product |
| `wc_update_product` | Update product details |
| `wc_get_store_stats` | Revenue, orders, product counts |
| `wc_list_orders` | List orders with status filter |
| `wc_get_order` | Get single order by ID |
| `wc_update_order_status` | Change order status |
| `wc_list_customers` | List customers |
| `wc_get_customers` | Get customer details |
| `wc_create_coupon` | Create a coupon |
| `wc_get_coupon` | Get coupon by ID or code |
| `wc_update_coupon` | Update coupon |
| `wc_delete_coupon` | Delete coupon (trash or force) |
| `wc_get_coupons` | List coupons |
| `wc_get_coupon_count` | Count by status (published/draft/trashed) |
| `wc_empty_coupon_trash` | Permanently delete all trashed coupons |
| `wc_get_product_attributes` | List global product attributes |
| `wc_create_product_attribute` | Register new global attribute taxonomy |
| `wc_get_attribute_terms` | Get terms for a global attribute |
| `wc_set_product_attributes` | Set which attributes a variable product uses |
| `wc_get_product_variations` | Get all variations for a variable product |
| `wc_get_variation` | Get single variation by ID |
| `wc_create_variation` | Create a product variation |
| `wc_update_variation` | Update a variation |
| `wc_delete_variation` | Delete a variation |
| `wc_batch_update_variations` | Batch create/update/delete variations |

---

## Email Tools — scope: `write`

| Tool | Description |
|---|---|
| `send_email` | Send email via wp_mail (to, subject, body, headers) |

---

## File Manager Tools — scope: `admin` (sandboxed to uploads/)

| Tool | Description |
|---|---|
| `list_files` | List files in uploads directory |
| `read_file` | Read file contents |
| `write_file` | Create or overwrite a file |
| `delete_file` | Delete a file |
| `fs_list_dir` | List directory entries |
| `fs_read_file` | Read file with path validation |
| `fs_uploads_info` | Get uploads path, URL, disk usage |
| `fs_delete_file` | Delete file (alias) |
| `fs_delete_dir` | Delete directory and contents |

---

## CLI Tools — scope: `admin`

| Tool | Description |
|---|---|
| `run_cli` | Execute WP-CLI command from allowlist via shell_exec |
| `cli_available` | Check if WP-CLI is installed and working |

**Security:** Command allowlist enforced, `escapeshellarg()` on all args, `--allow-root` appended automatically.

---

## Raw SQL Tools — scope: `admin` (disabled by default in settings)

| Tool | Description |
|---|---|
| `sql_query` | Execute a SELECT-only query via wpdb |
| `sql_describe_table` | Describe table columns |
| `sql_list_tables` | List all WP DB tables with row counts |

---

## Transient Tools — scope: `read` / `write`

| Tool | Description |
|---|---|
| `get_transient` | Get a transient value by key |
| `set_transient` | Set a transient with optional expiry |
| `delete_transient` | Delete a transient |
| `transient_list` | List transients matching a prefix/search |
| `transient_flush_expired` | Delete all expired transients |

---

## Widget Tools — scope: `read` / `write`

| Tool | Description |
|---|---|
| `list_widget_areas` | List all registered widget areas (sidebars) |
| `widget_list_areas` | Alias |
| `widget_list_registered` | List all registered widget types |
| `widget_get_area` | Get all widgets in a specific area with settings |
| `widget_update_area` | Reorder or set widget list for an area |
| `widget_remove` | Remove a widget from an area |

---

## Elementor Tools — scope: `elementor` (30 tools)

| Tool | Description |
|---|---|
| `elementor_create_page` | Create WP page with Elementor enabled |
| `elementor_add_container` | Add flex/grid container (root or nested via parent_id) |
| `elementor_add_heading` | Add heading widget (h1–h6, color, typography) |
| `elementor_add_text` | Add text/HTML editor widget |
| `elementor_add_button` | Add button widget (color, hover, border, radius, padding) |
| `elementor_add_image` | Add image widget |
| `elementor_add_widget` | Add any Elementor widget by type name |
| `elementor_get_page` | Get full Elementor JSON data for a page |
| `elementor_get_page_outline` | Get simplified structure (containers + widget types only) |
| `elementor_update_element` | Update any element's settings by element_id |
| `elementor_update_container` | Update container settings |
| `elementor_update_widget` | Update widget settings |
| `elementor_update_page_settings` | Update page-level Elementor settings |
| `elementor_delete_items` | Delete elements by id |
| `elementor_duplicate_element` | Duplicate any element in place |
| `elementor_move_element` | Move element to different parent/position |
| `elementor_replace_text` | Find and replace text across all widgets on a page |
| `elementor_clone_page` | Duplicate entire page as a new draft |
| `elementor_delete_page_content` | Clear all Elementor content from a page |
| `elementor_import_template` | Import page structure from Elementor template library |
| `elementor_export_page` | Export page as Elementor JSON |
| `elementor_save_as_template` | Save page to template library |
| `elementor_apply_template` | Apply template to a page |
| `elementor_list_templates` | List saved Elementor templates |
| `elementor_get_global_colors` | Get Elementor kit global color palette |
| `elementor_get_global_fonts` | Get Elementor kit font groups |
| `elementor_get_kit_settings` | Get full Elementor kit settings |
| `elementor_get_element` | Get single element by id from page data |
| `elementor_add_line` | Add line/divider widget |
| `elementor_add_block` | Add block widget |