Tools reference

Tools are what Octo can do. These tables show the defaults. In Settings → Tools you can switch configurable tools off and set the minimum role. Built-in chat helpers are listed separately below and do not appear in Settings. See Tool access and roles.

Approval means the approval window opens before the tool runs, unless the chat's permissions allow it.

Site and content (Free)#

Label	Name	What it does	Approval
WordPress Site Info	wp_get_site_info	Read-only site metadata.	No
Plugin and Theme Info	wp_get_plugin_theme_info	Active theme and installed plugins.	No
Public Post Types	wp_list_public_post_types	Public post types and labels.	No
Recent WordPress Posts	wp_list_recent_posts	Recent posts filtered by status; published by default. Use status: "all" for all statuses. Non-public posts require permission to read them.	No
Get Content Item	wp_get_content_item	Read content or focused settings, taxonomy, media and registered custom-field groups.	No
Inspect Content Revisions	wp_get_content_revisions	Page saved revisions or compare one revision with current content or another revision.	No
Search Content	wp_search_content	Search content by text and status with paging; published by default.	No
List Menus	wp_list_menus	Find classic menus and block navigation menus.	No
Get Menu	wp_get_menu	Inspect one menu's ordered, nested items. Dynamic items are identified, not rendered.	No
List Media	wp_list_media	Find files by search, MIME type, missing image alt text, parent or unattached state.	No
Get Media	wp_get_media	Read one file's alt text, caption, dimensions, available sizes and known file size.	No
List Users	wp_list_users	Find users by name or role, without contact details.	No
List Comments	wp_list_comments	Find comments by status, post or text, including pending, spam and trash.	No
List Taxonomies	wp_list_taxonomies	Discover readable taxonomies and associated post types.	No
List Terms	wp_list_terms	Search a taxonomy's categories, tags or other terms.	No
List Plugins	wp_list_plugins	Search installed plugins and filter activation state; shows cached update information.	No
List Themes	wp_list_themes	Search installed themes and filter active or parent/child state.	No

New list tools return 20 records per page by default, up to 50. WordPress permissions still apply even if a tool is enabled. Menu, user, plugin and theme tools default to administrator access. Comment reads require moderation permission; media reads require upload permission.

Content search accepts a registered status or all, including trash. Choose non-public admin-visible custom post types explicitly; postType: "all" covers public content types. Internal records such as revisions and WooCommerce orders/coupons use other tools. Search keeps its compact default of five results, up to ten per page.

Unattached media is not necessarily unused. Get Media can optionally look for native featured-image, block/gallery/HTML and WooCommerce product-image references, scanning at most 100 candidate records and returning up to 20 matches per request. Continue with its returned cursor when needed. Builder metadata, plugin options and theme files are excluded; skipped or unreadable records and incomplete coverage mean no matches is not proof of non-use. Plugin/theme update state comes from WordPress's existing cached check, so unknown does not mean up to date. These read tools never activate plugins/themes, run update checks, or change records.

Managing records#

Label	Name	What it changes	Approval
Manage Content	wp_manage_content	Create drafts, edit supported content fields, publish/schedule when requested, trash or restore posts/pages/custom content.	Yes
Manage Media	wp_manage_media	Import permitted files from public URLs or chat images; edit metadata/parent; trash or restore when supported.	Yes
Manage Term	wp_manage_term	Create or edit category, tag and other existing-taxonomy terms.	Yes
Manage Comment	wp_manage_comment	Create comments/replies as your account; edit, moderate, trash or restore.	Yes
Manage Menu	wp_manage_menu	Create classic/block menus; edit items, order and classic locations; trash/restore block menus.	Yes
Set Plugin Status	wp_set_plugin_status	Site-level activation/deactivation of one installed plugin.	Yes
Activate Theme	wp_activate_theme	Switch to one installed, site-allowed theme.	Yes

These tools default to administrator access and still enforce WordPress's native permissions. Chat auto-approval follows your existing settings. Choose an action; updates change only supplied fields. Content creation defaults to draft. Scheduled publication requires publishAt with a timezone offset. Taxonomy assignments use existing term IDs; an empty list clears an assignment. A featured image ID of zero clears it.

Focused content settings and recovery#

Get Content Item accepts groups: content, settings, taxonomies, media and customFields. Explicit groups return identity plus just the selected data. Omit groups for the existing full-item view, or zoom into a section without group selectors. Settings include supported parent, order, template, author and discussion controls. Manage Content can change these and post-only sticky state with native permissions.

The customFields group lists paginated descriptors for usable registered fields, including fields not exposed by the WordPress REST API. Supply metaKeys (up to 20) to read selected values and schemas. Editing requires content edit and per-field permissions. A meta map replaces supplied field values; null removes stored values. Unregistered fields and dedicated settings such as featured image/template are excluded. Values and submitted changes remain subject to normal chat retention.

Inspect Content Revisions lists saved revisions, excluding autosaves. Choose a revision to see bounded differences and a current-state token. Manage Content with action: "restore_revision" requires that token and revision ID; stale comparisons are rejected. Recovery restores title, body, excerpt and native revision-enabled custom fields, not publication status, taxonomy assignments or other settings. A field missing from the revision removes its current stored values; approval details show these removals. Unauthorized or incompatible fields block recovery before writing. On older WordPress without metadata revision support, only core content is restored and that limitation is reported. Published content changes immediately; server checks do not claim browser-side block validation.

Trash is not permanent deletion and is unavailable for some records/sites. Classic menus and terms cannot be deleted with these tools. Media trash requires the site's media-trash support. Restoring content does not silently republish it. Menu-item removal retains its existing behavior, including permanent removal of classic items. File replacement, general user-account edits, software installation/update and network changes are not provided.

Media URL imports accept file types permitted by WordPress, subject to the site's upload size limit. They reject private-network sources and unsafe redirects. This does not expand the file types accepted as chat attachments. Comment replies use parentId and the acting account's identity, never a fabricated author.

The five management names replace the former separate create/update/import tools. Saved access and selected-tool auto-approval move to the replacement when any predecessor granted access. That includes the replacement's new actions. Old tool names are no longer callable; a paused run using one may need restarting.

Menu edits require the revision returned by Get Menu. Refresh that read if the menu changed. Item batches are limited to 20 operations and inspected menus to 200 items/20 levels. Block paths refer to the inspected snapshot; referenced menus must be edited by their own IDs. Dynamic/unknown blocks are preserved, not rewritten. A failed multi-step edit may have saved some changes: inspect before retrying.

Plugin activation runs that plugin's normal activation code. It is not a sandbox or an automatic rollback. OctoPress cannot deactivate itself, remove a network-active plugin, or ignore native dependency checks. Theme switching can change the public appearance immediately.

Charts and tables (Free)#

Label	Name	What it does	Approval
Prepare Data Table	wp_prepare_data_table	Prepare a live, read-only table of site records with search, supported sorting, filters and paging.	No

The tool checks access and returns a table for Octo to include in its reply. Records load with the viewer's current permissions. Charts and ordinary tables are rendered directly from replies; there is no separate chart-generation tool. See Charts and tables.

Block editor (Free)#

Label	Name	What it does	Approval
Search Blocks	wp_block_search_blocks	Find registered block types.	No
Get Block Info	wp_block_get_block_info	Details of chosen blocks.	No
Get Content Outline	wp_block_get_content_outline	Section handles of an existing post for targeted updates.	No
Search Patterns	wp_block_search_patterns	Find block patterns.	No
Get Pattern	wp_block_get_pattern	One pattern's content.	No
List Pattern Categories	wp_block_list_pattern_categories	Categories with counts.	No
List Style Variations	wp_block_list_style_variations	Theme style variations.	No
Get Theme Design System	wp_block_get_theme_design_system	Colors, typography, spacing and layout of the active block theme.	No
Validate Block Content	wp_block_validate_content	Check block markup before writing.	No

Use Manage Content above with block validation and outline tools for safe section editing. action: "update" retains replace, append, prepend and hash-checked section patches; large drafts can be saved incrementally.

WordPress and plugin abilities (Free)#

Other plugins can expose actions through the WordPress Abilities API. They appear as wp_ability__<plugin>__<action>, for example wp_ability__core__get_site_info or wp_ability__core__get_environment_info, in groups named Abilities: …. Their risk and approval follow the ability. Review them in Settings → Tools.

WooCommerce products and orders (Free)#

With WooCommerce active, List Products, Get Product and Manage Product (wc_list_products, wc_get_product, wc_manage_product) handle simple, variable, grouped and external products plus individual variations. New products default to draft. Inventory reads identify the parent or variation that owns stock.

Product catalog details include existing brand IDs when brands are available. Discovery can filter by brandId. The opt-in merchandising group includes upsell/cross-sell IDs, menu order, purchase note and review availability. Updates use existing readable product/brand IDs and preserve omitted fields; relationship arrays share the 20-item mutation limit. These parent-product settings do not apply to variations. Brand vocabulary management remains Pro.

List Orders, Get Order, Manage Order and List Order Notes (wc_list_orders, wc_get_order, wc_manage_order, wc_list_order_notes) support pending-first creation, partial updates, status changes, native trash/restore and append-only notes. Notes are internal unless explicitly made customer-visible. Native stock, email and totals behavior remains active. Financial changes cannot bypass WooCommerce's order editability rules.

Collections are paginated (20 by default, maximum 50). Details request only needed groups; contact/address data and line items are not loaded during ordinary discovery. Managers require approval unless current chat permissions allow them. Refunds, gateway payment actions, permanent deletion and changing an existing product's type are not supported. These are OctoPress-owned tools; no WooCommerce Abilities API support is required.

SEO (Pro)#

Label	Name	Approval
Detect SEO Plugin	seo_detect_plugin	No
Get Content SEO	seo_get_content_seo	No
Get Content SEO Score	seo_get_content_score	No
Get Rendered SEO Preview	seo_get_rendered_preview	No
Find Content Needing SEO Updates	seo_find_content_needing_updates	No
Update Content SEO	seo_update_content_seo	Yes
Bulk Update Content SEO	seo_bulk_update_content_seo	Yes

WooCommerce store (Pro)#

Store configuration stays read-only: wc_get_store_status, wc_list_payment_methods, wc_list_shipping_zones, wc_get_tax_settings. See WooCommerce.

Catalog discovery/detail/management uses wc_list_catalog, wc_get_catalog_item and wc_manage_catalog. Select categories, tags, available brands, shipping classes, global attributes or attribute terms. Catalog supports creation/update, not deletion; attribute terms require their attribute ID.

Pro also includes wc_list_coupons (search, status, usage limits and expiration) and wc_list_customers (registered customer names and creation dates). Both are paginated, default to administrator access, and require native WooCommerce permissions. They omit contact details, addresses, payment data and raw metadata. Guest-order identities are not included in the customer list.

wc_get_coupon and wc_get_customer read one record with optional detail groups. wc_manage_coupon creates, updates, trashes or safely restores coupons. wc_manage_customer creates registered customers with generated credentials or changes supplied names, email and billing/shipping fields. It never converts an existing account or deletes one. Native permissions always apply.

wc_list_reviews, wc_get_review and wc_manage_review inspect and moderate product reviews, trash/restore them and add store replies as the acting user. Buyer review creation, author/rating/verified-purchase edits and permanent deletion are excluded.

List one review's replies with reviewId and pagination, then inspect a selected reply by its own ID. Reply updates, trash and restore retain the author and parent-review/product relationships. Threads never expand automatically.

Customer contact/address groups expose personal data. Retrieve only what the task needs; submitted values and approvals can remain in chat history. Staff/privileged accounts, usernames, passwords, roles, payment data and arbitrary metadata are excluded. Mutation confirmations remain compact instead of returning whole records.

Development (Pro)#

Label	Name	Risk	Approval
List project files	fp_list_files	Read	No
Read project file	fp_read_file	Read	No
Search files	fp_search_files	Read	No
Write project file	fp_write_file	File write	Yes
Replace in project file	fp_replace_in_file	File write	Yes
Create project directory	fp_create_directory	File write	Yes
Apply project patch	fp_apply_patch	File write	Yes
PHP Syntax Lint	fp_php_lint	Validation	No
npm Typecheck	fp_npm_typecheck	Validation	No
npm Build	fp_npm_build	Validation	No
Run shell command	fp_run_command	Shell	Yes, disabled by default
Run PHP code	fp_run_php_code	Code execution	Yes

See Plugin and theme development.

Schedules (Pro)#

Label	Name	Approval
Get script schedules	fp_get_script_schedules	No
Create script schedule	fp_create_script_schedule	Yes, always asks
Update script schedule	fp_update_script_schedule	Yes, always asks
Run script schedule	fp_run_script_schedule	Yes, always asks
Delete script schedule	fp_delete_script_schedule	Yes, always asks

OpenAI hosted tools (Pro)#

Label	Name	What it does	Approval
Use hosted web access	op_web_access	Search the web or open a URL with OpenAI's hosted tool.	No
Generate image	op_generate_image	Generate an image and save it as a chat attachment.	Yes

Both are offered only with a ChatGPT Login or OpenAI API Key provider.

Built into chats#

These tools are part of how chats work and are not listed in Settings: asking a question, proposing a plan, handing off to another agent, loading a skill's instructions, and re-reading an earlier image.

Local documentation helpers are included in both editions:

Label	Name	What it does	Approval
Search OctoPress help	op_search_help	Find relevant pages and sections in the documentation bundled with the plugin.	No
Read OctoPress help	op_read_help	Read a matching page or section, with documentation and relevant admin-screen links.	No

These helpers are available independently of an agent's skill selection. They do not fetch the website, diagnose the site, or change settings. Pro documentation is labeled Pro and does not unlock Pro features. See Ask Octo for help.