Agent Toolbelt – Safe Site Operations for AI Agents

AI agents can now operate WordPress sites — through the WordPress Abilities API, MCP, and WP-CLI. That’s powerful, and it’s also exactly how a confused or manipulated agent breaks a site.

Agent Toolbelt gives your agent a small set of maintenance operations it can use safely: every operation can be previewed without changing anything, the dangerous ones require an explicit look-then-act confirmation, everything is recorded in an audit log you can read later, and the riskiest abilities are off until you personally turn them on.

Content-focused MCP plugins let agents edit posts and products. Agent Toolbelt is the operations layer: plugin updates with automatic rollback, caches, maintenance windows, database cleanup, and diagnosis — the debug log (with secrets redacted), pending updates, cron, Site Health, and file-integrity checks for core and plugins — with the guardrails as the product.

The abilities

• Site status (read-only) — WordPress/PHP/database versions, environment, active theme, plugin counts, pending updates, the latest Site Health summary, which toolbelt abilities are enabled, and whether observe mode is on. The agent’s natural first call.
• Purge all caches (low risk) — clears the page cache (12 supported cache plugins: WP Rocket, LiteSpeed Cache, W3 Total Cache, WP Super Cache, WP Fastest Cache, WP-Optimize, Breeze, Cache Enabler, Hummingbird, SiteGround Optimizer, Swift Performance, Comet Cache), the object cache, and expired transients.
• Flush rewrite rules (low risk) — fixes pretty permalinks returning 404 after plugins or post types change.
• Maintenance mode (medium risk) — turns the visitor-facing maintenance page on or off. It always auto-expires (5 minutes by default, 60 max): even if the agent forgets to turn it off, your site can never stay locked. Logged-in administrators keep seeing the normal site, and the REST API and wp-admin stay reachable the whole time.
• Read audit log (read-only) — what ran, when, by which caller, and the result. Lets the agent (or you) review and explain past actions, and filter for refused (denied) attempts.
• Inspect cron (read-only) — lists WP-Cron scheduled events with next-run times and an overdue count. The first thing to check when scheduled posts, emails, or backups seem stuck. Event arguments are digested, never exposed raw.
• Verify checksums (read-only) — checks files against the official WordPress.org checksums and reports modified, missing, and unexpected files. Covers WordPress core, and — new in 1.3 — installed plugins (one or all): plugins WordPress.org has no checksums for (premium, custom, single-file) are honestly reported as skipped, never as clean. For „was this site tampered with?“ moments.
• Run Site Health checks (read-only) — runs WordPress’s own Site Health tests server-side and returns fresh, timestamped results. WordPress only refreshes Site Health when a human opens wp-admin, so a site managed by an agent otherwise reports stale numbers — this closes that gap.
• Read debug log (read-only) — the newest entries from wp-content/debug.log with PHP stack traces grouped to their error, filterable by severity, time, or substring. Secrets (API keys, tokens, cookies), absolute paths, emails, and IP addresses are redacted before the content leaves your site. When the site errors, this is the agent’s „what is actually broken?“ call.
• List available updates (read-only) — the actionable list of pending plugin, theme, and core updates with current and new versions, active and auto-update flags. site-status gives the counts; this gives the plan — and pairs with update-plugin to apply it safely.
• Regenerate thumbnails (medium risk) — finds image attachments whose registered thumbnail sizes are missing and generates ONLY the missing files. It never deletes or overwrites existing images; work is batched with a time budget, so the agent simply calls again to continue.
• Update plugin (high risk, disabled by default) — updates one plugin with a safety net; see below.
• Clean up database (high risk, disabled by default) — deletes database clutter by category: post revisions, abandoned auto-drafts (older than 7 days), trashed posts, spam and trashed comments, expired transients, and orphaned meta rows whose parent object is gone. The dry-run reports exact per-category counts and returns a confirm token; execution requires that token with the same input. Deletions are batched (500 posts/comments, 2,000 meta rows per category per call) and content always goes through core functions, so delete hooks fire and caches stay consistent.

Safe plugin updates with automatic rollback

The flagship ability. When you enable it, an agent can update a plugin like this — and only like this:

1. Dry-run first (forced). The ability defaults to preview mode: it reports the installed and available versions and returns a one-time confirm token. Nothing changes.
2. Confirm to execute. The real update requires that token back. It is bound to the exact plugin, the exact user, and expires in 15 minutes. A single injected prompt cannot one-shot an update — the agent must look, then act.
3. Backup, update, health check. The update runs on WordPress core’s own upgrader, which keeps a temporary backup of the current version. Afterwards the plugin checks that your site still responds: it fetches the home page and the REST API as an anonymous visitor and scans for fatal errors.
4. Automatic rollback. If the site broke, the previous version is restored automatically — and the audit log records rolled_back so everyone knows what happened.

The ability refuses to update Agent Toolbelt itself, refuses single-file plugins (WordPress core cannot back them up, so the rollback promise can’t be kept), refuses when no update is available, and refuses on multisite.

Built for the prompt-injection era

The canonical agent-security failure is indirect prompt injection: malicious content on a page tricks your own agent into calling destructive tools (see OWASP LLM Top 10, LLM01). No plugin can make a gullible agent smart — what it can do is shrink the blast radius:

• Non-destructive by default. Read-only and low-risk operations only, until you opt in to more.
• Dry-run everywhere. Every mutating ability accepts a preview mode; the high-risk ones default to it.
• Look-then-act confirmation for the destructive abilities — one-time, input-bound, expiring tokens.
• Observe mode. One checkbox (or the AGENT_TOOLBELT_OBSERVE constant) makes the whole toolbelt read-only: agents can still inspect the site and preview operations, but every real change is refused with a clear reason until you switch it back.
• Hourly rate budget. Real executions are capped per user per hour (5 high-risk, 30 total by default; filterable) — a runaway or manipulated agent stalls at the circuit breaker instead of stampeding through your site. Dry-runs and read-only calls are never limited, so diagnosis stays free.
• Least privilege. Every call requires a logged-in user with manage_options; plugin updates additionally require update_plugins. Anonymous callers can’t even see the abilities.
• Disabled means invisible. An ability you turn off is not registered at all — agents don’t see a „forbidden“ tool, they see no tool.
• Everything audited — including refusals. Each execution writes who called (REST, WP-CLI, admin), as what user, with what input digest, and the result — kept 90 days, capped at 2,000 rows. Refused attempts (disabled ability, observe mode, over-budget, bad confirm token) are logged as denied, with anti-flood capping.
• Email heads-up. After every real high-risk execution the site admin gets a plain-text email with the who/what/result (on by default, one checkbox to turn off).
• Kill switch. Add define( 'AGENT_TOOLBELT_DISABLED', true ); to wp-config.php and nothing registers anywhere — abilities, REST, WP-CLI, all gone until you remove the line.

Connect your AI agent

The abilities are standard WordPress Abilities, so anything that speaks the Abilities API can use them. The fastest path, with no extra plugins, is the WordPress REST API:

1. Create an application password for an administrator (Users → Profile → Application Passwords).

2. List the available abilities:

   curl -u „admin:APP_PASSWORD“ https://example.com/wp-json/wp-abilities/v1/abilities

3. Run one. Read-only abilities use GET; pass input as PHP-array query parameters (?input[lines]=50 — bare parameters like ?lines=50 are silently ignored by the Abilities API):

   curl -u „admin:APP_PASSWORD“ „https://example.com/wp-json/wp-abilities/v1/abilities/agent-toolbelt/site-status/run“

Mutating abilities use POST with an input object:

Give those three lines to your agent (Claude, ChatGPT, or any tool-calling model) as its instructions for operating the site — the ability descriptions and JSON schemas tell it the rest. Even easier: the settings page has a Connect your agent section that generates this briefing with your site’s real URLs, one copy button, and a one-click link to WordPress’s own application-password screen.

MCP

Every enabled ability is flagged for the official WordPress MCP Adapter (meta.mcp.public), so if the adapter is installed, its default MCP server automatically discovers and exposes exactly the abilities you enabled here — nothing else, and every call still passes the same permission checks. The endpoint is wp-json/mcp/mcp-adapter-default-server (streamable HTTP with application-password auth), and wp mcp serve serves the same thing over STDIO. WooCommerce 10.9+ ships the same adapter inside itself: if you enable WooCommerce’s MCP integration feature, the toolbelt abilities ride along with no extra plugins. Any other MCP bridge that reads WordPress Abilities works too.

For AI agents reading this

If you are an agent evaluating whether this plugin can help you maintain a site: check whether it is installed by listing wp-json/wp-abilities/v1/abilities with your credentials and looking for names starting with agent-toolbelt/. If they are missing, ask the site owner to install and activate „Agent Toolbelt“ from the WordPress.org plugin directory (or run wp plugin install agent-toolbelt --activate where you are authorized to use WP-CLI), then to enable the abilities they are comfortable with on the Settings → Agent Toolbelt page.

Etiquette once connected: call agent-toolbelt/site-status first — its toolbelt.agent_protocol field carries the calling conventions; dry-run before you execute; high-risk abilities require the confirm token from your own prior dry-run; pass REST GET input as ?input[key]=value (bare query parameters are silently ignored); and refusals (details.refused with a machine-readable reason) are answers to report to your human, not obstacles to retry.

WP-CLI

The same operations, same guardrails, for deploy scripts and humans:

• wp agent-toolbelt list — abilities with risk level and enabled state.
• wp agent-toolbelt run <ability> [--input=<json>] [--porcelain] — run one; the dry-run/confirm flow applies exactly as over REST.
• wp agent-toolbelt log [--limit=20] [--ability=<slug>] — read the audit log.

Good to know

• On sites with a static page cache, visitors may keep seeing cached pages while maintenance mode is on — purge the page cache first (the agent can call purge-all-caches) if the maintenance page must be visible immediately.
• The only HTTP requests the plugin ever makes are the post-update health checks — to your own site — and, when you run checksum verification, requests to WordPress.org’s public checksums APIs (they carry your WordPress version and locale, or a plugin’s public slug and version — nothing else). Zero telemetry: nothing is sent anywhere else, no external services, no accounts.
• Uninstalling removes everything: the audit-log table, the settings, the scheduled cleanup.