Description

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:

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

Create an application password for an administrator (Users Profile Application Passwords).
List the available abilities:

curl -u “admin:APP_PASSWORD” https://example.com/wp-json/wp-abilities/v1/abilities
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:

curl -u "admin:APP_PASSWORD" -X POST -H "Content-Type: application/json" -d '{"input":{"dry_run":true}}' https://example.com/wp-json/wp-abilities/v1/abilities/agent-toolbelt/purge-all-caches/run

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.

Screenshots

The ability checklist with risk badges — enable exactly what your agent may do.

The audit log — every operation with caller, user, input digest and result. — The ability checklist with risk badges — enable exactly what your agent may do.

FAQ

Is it really safe to let an AI agent update plugins?: “Safe” here means: previewed, confirmed, backed up, health-checked, and rolled back automatically if the site breaks — with an audit trail. That’s more protection than a human clicking “Update now” gets. It’s still a change to your site, which is why the ability ships disabled and you must enable it deliberately.
What stops a prompt-injected agent from wrecking my site?: Several layers: the destructive abilities are off by default; if you enabled them, execution needs a fresh one-time confirm token from a prior dry-run of the same request (a single malicious instruction can’t do both steps blindly); every call needs an authenticated administrator — content on your pages can’t call anything by itself; the hourly rate budget stalls a stampede; and observe mode lets you cut all write access with one checkbox while you investigate. The honest part: if your agent has admin credentials and is fully compromised, no plugin can save you — the toolbelt’s job is to make the destructive path narrow, slow, and visible.
Why does update-plugin refuse single-file plugins like Hello Dolly?: WordPress core’s temporary-backup mechanism skips plugins that live in a single file, so there would be no backup to roll back to. Rather than update without a safety net, the ability refuses and tells the agent to use wp-admin or WP-CLI instead.
Does it work on multisite?: Everything except plugin updates. Network-wide update semantics deserve their own careful design, so on multisite the update ability refuses with a clear reason instead of guessing.
Can visitors or logged-out agents see or call the abilities?: No. Every ability requires a logged-in user with manage_options (updates also need update_plugins). Anonymous REST calls get a 401, and the abilities don’t even appear in the listing for unauthorized users.
How do I turn everything off in an emergency?: Two ways: untick abilities on the Settings Agent Toolbelt page (they unregister instantly), or add define( 'AGENT_TOOLBELT_DISABLED', true ); to wp-config.php — the kill switch unregisters everything: abilities, REST exposure, and the WP-CLI command. There is also a softer option: observe mode (see below) keeps the abilities visible but read-only.
What is observe mode?: A read-only switch for the whole toolbelt. While it is on (checkbox on the settings page, or force it with define( 'AGENT_TOOLBELT_OBSERVE', true ); in wp-config.php), agents can still call read-only abilities and preview any operation with dry-run, but every real change is refused with the machine-readable reason observe_mode and a message telling the agent to ask you. Useful while you are getting to know a new agent, or any time you want eyes-only access without hiding the tools.
Can a runaway agent execute operations in a loop?: Not for long. Real executions are rate-limited per user with a fixed hourly budget: 5 high-risk and 30 total mutating executions per hour by default (the agent_toolbelt_rate_budgets filter changes the numbers; define( 'AGENT_TOOLBELT_NO_RATE_LIMIT', true ); disables the limit for supervised bulk-maintenance sessions). Over-budget calls are refused with the reason rate_budget and a retry_after_s hint, and land in the audit log as denied — so a stampeding agent both stalls and leaves a visible trail. Dry-runs and read-only abilities are never counted: diagnosis stays free.
Why is the database cleanup disabled by default?: Because it deletes content — revisions, trashed posts, spam, orphaned rows. That is exactly what you want from a cleanup, but a tool that can delete rows the moment the plugin activates would contradict what this plugin promises. So you enable it consciously, once, on the settings page. After that the usual guardrails apply: dry-run with exact per-category counts, a one-time confirm token bound to the same input, batched deletes through core functions, and an audit-log entry plus an email for every real execution.
What exactly does cleanup-database delete?: Only well-defined garbage, by category — and you can pass a categories list to run any subset: post revisions; auto-drafts older than 7 days; trashed posts; spam and trashed comments; expired transients; and orphaned post/comment/term/user meta rows whose parent object no longer exists. It never touches published content, drafts, users, terms, or settings. Posts and comments are deleted through WordPress core functions (wp_delete_post, wp_delete_comment), so cleanup hooks fire and caches stay consistent.
Why don’t I see maintenance mode when I turn it on?: If you are logged in as an administrator, that’s on purpose — administrators always see the normal site. Open a private/incognito window to see what visitors get. Otherwise, a static page cache is probably serving visitors a cached copy: purge the page cache (there’s an ability for that) and reload. Maintenance mode always auto-expires, so a forgotten “on” can never lock the site permanently.
How does my agent discover the abilities?: Three doors, all showing exactly (and only) what you enabled: the WordPress REST API listing at wp-json/wp-abilities/v1/abilities; the official MCP Adapter’s default server, which picks up the toolbelt’s abilities automatically because they carry the meta.mcp.public flag; and the Abilities Explorer in the official ai plugin, if you use it. The Connect your agent section on the settings page turns this into a copy-paste briefing with your site’s real URLs.
Does it work with the official WordPress MCP Adapter?: Yes, out of the box. Enabled abilities are flagged meta.mcp.public, which is precisely what the adapter’s default server exposes; disabled abilities are not registered at all, so no transport can see them. Every MCP call still runs through the same permission checks, dry-run defaults, confirm tokens, rate budget, and audit log as REST — the transport changes, the guardrails don’t. If you want an ability callable over REST but hidden from MCP, the agent_toolbelt_mcp_public filter does that per ability.
Can read-debug-log leak my secrets to the agent?: The debug log is the one file on a WordPress site that routinely catches secrets — API keys inside stack traces, database credentials in connection errors, customer emails in mailer failures. That’s why redaction is built in and cannot be turned off: provider API keys, JWTs and bearer tokens, database credentials, URL query secrets, auth cookies and nonces, absolute filesystem paths, emails, and IP addresses are all masked before the content leaves your site. Two honest caveats: redaction is best-effort pattern matching (a secret in a format nobody has seen before can slip through — the response says so), and the search filter deliberately matches the redacted text, so an agent cannot use it to probe whether a specific secret value appears in the log. If that residual risk is still too much for your site, untick the ability — like everything else, disabled means invisible.
Why does verify-checksums skip my premium plugins?: WordPress.org only publishes checksums for plugins it distributes. Premium, custom, and single-file plugins have no official reference to compare against, so the ability reports them as skipped with a machine-readable reason — deliberately not as “clean”, because no evidence is not a clean bill. Agents are told the same in the ability description.
Does the plugin send any data anywhere?: Almost never, and never about you. The only HTTP requests it makes are health-check requests to your own site after a plugin update, and — only when you run verify-checksums — requests to WordPress.org’s public checksums APIs carrying your WordPress version and locale (core scope) or a plugin’s public slug and version (plugin scope). There is no telemetry, no phoning home, no external service.

Reviews

There are no reviews for this plugin.

Contributors & Developers

“Agent Toolbelt – Safe Site Operations for AI Agents” is open source software. The following people have contributed to this plugin.

Kostya Tereshchuk

Translate “Agent Toolbelt – Safe Site Operations for AI Agents” into your language.

Interested in development?

Browse the code, check out the SVN repository, or subscribe to the development log by RSS.

Changelog

1.3.1

The plugin page moved from Tools to Settings (Settings Agent Toolbelt) — where the refusal messages and the high-risk email already pointed, and where users expect a plugin’s settings to live.
The Plugins screen row now has a Settings action link next to Deactivate.
Connect your agent: the application-password explanation moved to its own line under the button.

1.3.0

New ability: read-debug-log (read-only, on by default) — the newest debug-log entries with stack traces grouped to their error and filters for severity, time, and substring. Secrets (API keys, JWTs, bearer tokens, database credentials, cookies, nonces), absolute paths, emails, and IPs are redacted before the content leaves the site; the substring filter matches the redacted text, so it cannot be used to probe for raw secret values. Reads are bounded (a tail of at most 1 MB), so huge logs are safe to query.
verify-checksums now also covers plugins: scope=plugin verifies one named plugin or every installed plugin against WordPress.org’s plugin-checksums API, with per-plugin results, unexpected-file detection inside each plugin directory, and honest skipped-with-reason reporting for premium/custom/single-file plugins (skipped is not clean).
New ability: list-available-updates (read-only) — pending plugin, theme, and core updates with current/new versions and active/auto-update flags; the actionable companion to site-status’s counts and update-plugin’s execution.
site-status now includes toolbelt.agent_protocol — the dry-run, confirm-token, refusal, and REST calling conventions travel with the first call every agent makes.
Every ability now exposes the complete readonly/destructive/idempotent annotation set, so MCP clients receive full ToolAnnotations hints (readOnlyHint, destructiveHint, idempotentHint) through the official adapter.
Documentation now spells out the Abilities API GET input syntax (?input[key]=value — bare query parameters are silently ignored) in the readme, the Connect-your-agent briefing, and agent_protocol.
Fixed an outdated code comment claiming confirm-token refusals are not logged (they are logged as denied since 1.1.0; the behavior was always correct, the comment was not).

1.2.0

MCP-native: every enabled ability now carries the meta.mcp.public flag, so the official WordPress MCP Adapter’s default server (and WooCommerce’s bundled MCP integration) discovers and exposes it automatically; the agent_toolbelt_mcp_public filter can keep any ability REST-only.
New ability: inspect-cron (read-only) — WP-Cron events with next-run times and an overdue count, for “scheduled things seem stuck” diagnosis; event args are digested, never exposed.
New ability: verify-checksums (read-only) — verifies core files against official WordPress.org checksums; reports modified, missing, and unexpected files under wp-admin/wp-includes; time-budgeted with a resume cursor.
New ability: run-site-health-checks (read-only) — runs Site Health’s direct tests server-side with a real timestamp (core only refreshes them when a human visits wp-admin); site-status now reports the fresh counts as health_fresh.
Connect your agent: a new settings-page section with your site’s actual endpoint URLs, a one-click link to WordPress’s own application-password screen, MCP status, and a copyable agent briefing.
Readme: a “For AI agents reading this” section and refreshed MCP documentation.

1.1.0

New ability: regenerate-thumbnails (medium risk) — finds image attachments with missing thumbnail sizes and generates only the missing files; batched, time-budgeted, never deletes or overwrites.
New ability: cleanup-database (high risk, disabled by default) — deletes revisions, old auto-drafts, trashed posts, spam/trashed comments, expired transients, and orphaned meta rows; exact per-category dry-run counts, confirm token bound to the same input, batched deletes through core APIs.
Observe mode: a read-only switch for the whole toolbelt (settings checkbox or the AGENT_TOOLBELT_OBSERVE constant) — agents can look and preview, nothing mutates.
Hourly rate budget for real executions (5 high-risk / 30 total per user per hour, filterable via agent_toolbelt_rate_budgets; AGENT_TOOLBELT_NO_RATE_LIMIT bypass) with retry_after_s in the refusal.
Denied attempts (disabled ability, observe mode, over-budget, bad confirm token) are now recorded in the audit log as denied, with anti-flood capping.
Audit log can be filtered by result on every surface: the read-audit-log ability, wp agent-toolbelt log --result=denied, and the reader API.
Email notification to the site admin after every real high-risk execution (on by default; settings checkbox).
site-status now reports observe_mode alongside the toolbelt version and enabled abilities, so agents learn the safety state on their first call.
Permission gate is per-operation: update-plugin still requires update_plugins; cleanup-database needs only manage_options, so it keeps working on hosts that set DISALLOW_FILE_MODS.
High-risk dry-runs no longer issue a confirm token when the request is refused or observe mode is on (a token that can never execute would only mislead the agent).

1.0.0

Initial release.
Six abilities: site-status, purge-all-caches, flush-rewrite-rules, maintenance-mode (auto-expiring), read-audit-log, and update-plugin (opt-in) with backup, loopback health check and automatic rollback.
Guardrails: dry-run on every mutating ability, one-time confirm tokens for high-risk execution, per-ability enable/disable (disabled = invisible), audit log with 90-day/2,000-row retention, kill-switch constant.
Surfaces: WordPress Abilities API (REST wp-abilities/v1, MCP-ready), WP-CLI (wp agent-toolbelt), and an admin page under Tools.

Description

The abilities

Safe plugin updates with automatic rollback

Built for the prompt-injection era

Connect your AI agent

MCP

For AI agents reading this

WP-CLI

Good to know

Screenshots

FAQ

Is it really safe to let an AI agent update plugins?

What stops a prompt-injected agent from wrecking my site?

Why does update-plugin refuse single-file plugins like Hello Dolly?

Does it work on multisite?

Can visitors or logged-out agents see or call the abilities?

How do I turn everything off in an emergency?

What is observe mode?

Can a runaway agent execute operations in a loop?

Why is the database cleanup disabled by default?

What exactly does cleanup-database delete?

Why don’t I see maintenance mode when I turn it on?

How does my agent discover the abilities?

Does it work with the official WordPress MCP Adapter?

Can read-debug-log leak my secrets to the agent?

Why does verify-checksums skip my premium plugins?

Does the plugin send any data anywhere?

Reviews

Contributors & Developers

Interested in development?

Changelog

1.3.1

1.3.0

1.2.0

1.1.0

1.0.0

Meta

Ratings

Contributors

Support

Donate