The wp-mcp-control-server connects AI assistants (Cursor, Claude Desktop, etc.) to WordPress, providing 100+ tools across the following areas:
Site & Settings
Health checks, site info, theme/plugin lists, activity logs, cache purge, security posture
Read/update safe settings (title, tagline, front page, posts per page)
Content Management
Full CRUD for pages, posts, categories, tags, menus, and URL redirects
Build structured landing pages (hero, services, testimonials, FAQ, CTA sections)
Unified search across all content types
Media Library
List, get, upload (from URL or base64), update metadata, and delete media items
Elementor Page Builder
Browse widget catalog, get/list full page element tree, find widgets by type
Update widgets by ID, matched text, button text, or image URL
Insert, remove, clone elements/sections; duplicate entire pages; regenerate CSS cache
Gutenberg & Custom Post Types
Manage Gutenberg blocks and insert block patterns
CRUD for custom post types, custom taxonomies, terms, and ACF/meta fields
SEO
Get, update, and audit page SEO metadata
WooCommerce
CRUD for products, orders, bookings, and refunds; update prices; add order notes
Forms, Users, Comments & Widgets
List forms, submissions, and notifications; manage users and roles; moderate comments; update sidebar widgets
Revisions, Plugins & Cron
List/restore content revisions and snapshots; detect plugin conflicts; activate/deactivate plugins; list cron events
Webhooks
Manage custom, WooCommerce, and form webhooks
Batch Operations
Execute up to 20 API calls in a single request
Utilities
Export full site structure as JSON; generate sitemaps in JSON or XML
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@wp-mcp-control-server Create a new page titled 'About Us' using the default template"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
TypeScript MCP server that connects Cursor, Claude Desktop, and other MCP clients to the WP MCP Control WordPress plugin.
Current version: 2.3.0 (149 tools)
git clone https://github.com/mpierre135/wp-mcp-control-server.git
cd wp-mcp-control-server
npm install
npm run build
cp .env.example .env
# Edit .env with your site URL and tokenThen add to Claude Desktop or Cursor (see below).
Related MCP server: wp-cli-mcp
npm install
cp .env.example .env
# Edit .env with your credentials
npm run build
npm startVariable | Required | Default | Description |
| Yes | — | WordPress site URL (no trailing slash) |
| Yes | — | API token from plugin settings |
| No |
| Block destructive operations |
| No |
| Validate without making changes |
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"wp-mcp-control": {
"command": "node",
"args": ["/absolute/path/to/wp-mcp-control-server/dist/index.js"],
"env": {
"WP_MCP_SITE_URL": "https://example.com",
"WP_MCP_TOKEN": "your-token",
"WP_MCP_SAFE_MODE": "true",
"WP_MCP_DRY_RUN": "false"
}
}
}
}Restart Claude Desktop after saving.
{
"mcpServers": {
"wp-mcp-control": {
"command": "node",
"args": ["/absolute/path/to/mcp-server/dist/index.js"],
"env": {
"WP_MCP_SITE_URL": "https://example.com",
"WP_MCP_TOKEN": "your-token",
"WP_MCP_SAFE_MODE": "true",
"WP_MCP_DRY_RUN": "false"
}
}
}
}npm run dev # Watch mode
npm run build # Compile to dist/wp_health_check — Health and status
wp_get_site_info — Site metadata
wp_list_themes / wp_list_plugins — Read-only inventory
wp_get_settings / wp_update_settings — Safe settings
wp_list_pages, wp_get_page, wp_create_page, wp_update_page, wp_delete_page
wp_create_landing_page — Structured landing page builder
wp_list_posts, wp_get_post, wp_create_post, wp_update_post, wp_delete_post
wp_list_media, wp_get_media
wp_upload_media_from_url, wp_upload_media_from_base64
wp_update_media_metadata, wp_delete_media
wp_list_categories, wp_create_category, wp_update_category, wp_delete_category
wp_list_tags, wp_create_tag, wp_update_tag, wp_delete_tag
wp_list_menus, wp_get_menu_items
wp_create_menu_item, wp_update_menu_item, wp_delete_menu_item
wp_assign_menu_location
wp_search_content — Unified search
wp_batch_operations — Batch API calls
wp_get_activity_log, wp_restore_snapshot
wp_list_redirects, wp_create_redirect, wp_update_redirect, wp_delete_redirect
wp_export_site_structure, wp_generate_sitemap
wp_elementor_get_widget_catalog — Widget catalog with editable settings
wp_elementor_get_structure — Full Elementor element tree
wp_elementor_list_elements — Flat list of widgets with text previews
wp_elementor_find_widgets — Filter by widget_type
wp_elementor_update_element — Update catalog-editable widget by element ID
wp_elementor_update_text — Find widget by text and replace
wp_elementor_update_button — Update button text/URL by match_text
wp_elementor_update_image — Update image by element_id or match_url
wp_elementor_insert_widget — Add widget to column/container
wp_elementor_insert_section — Add section (hero/cta/features presets)
wp_elementor_remove_element — Delete element by ID
wp_elementor_clone_element — Clone subtree with new IDs
wp_elementor_duplicate_page — Clone Elementor page as draft
wp_elementor_find_parent — Find column/container for insert
wp_elementor_regenerate_css — Regenerate Elementor CSS cache
wp_get_site_blueprint, wp_site_audit, wp_security_posture, wp_purge_cache
wp_list_blocks, wp_update_block, wp_insert_block_pattern
wp_list_post_types, wp_list_cpt_items, wp_get_cpt_item, wp_create_cpt_item, wp_update_cpt_item, wp_delete_cpt_item
wp_list_taxonomies, wp_list_taxonomy_terms, wp_create_taxonomy_term
wp_get_meta_catalog, wp_get_acf_fields, wp_update_acf_fields
wp_get_page_seo, wp_update_page_seo, wp_audit_seo
wp_list_products, wp_get_product, wp_create_product, wp_update_product, wp_delete_product, wp_update_product_price
wp_list_orders, wp_get_order, wp_update_order, wp_add_order_note, wp_refund_order
wp_list_booking_products, wp_get_booking
wp_list_forms, wp_get_form, wp_update_form_notifications, wp_list_form_submissions
wp_list_users, wp_get_user, wp_list_roles, wp_create_user
wp_list_comments, wp_moderate_comment, wp_reply_to_comment
wp_list_sidebars, wp_list_widget_instances, wp_update_widget_instance
wp_list_revisions, wp_get_revision, wp_get_revision_diff, wp_restore_revision, wp_get_snapshot_diff
wp_get_plugin_conflicts, wp_get_plugin_updates, wp_activate_plugin, wp_deactivate_plugin
wp_list_cron_events
wp_list_webhook_topics, wp_list_custom_webhooks, wp_create_custom_webhook, wp_test_custom_webhook
wp_list_woocommerce_webhooks, wp_create_woocommerce_webhook, wp_delete_woocommerce_webhook
wp_list_form_webhooks, wp_create_form_webhook, wp_update_form_webhook, wp_delete_form_webhook
Server version: 2.3.0 — 149 tools total
Every request includes:
Authorization: Bearer <token>
X-WP-MCP-Dry-Run: true|false
X-WP-MCP-Safe-Mode: true|false
These override plugin defaults when set in MCP env vars.
Activate a plugin by slug (e.g. litespeed-cache/litespeed-cache.php). Must be on MCP allowlist. confirm required in safe mode.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Plugin file path relative to wp-content/plugins/ | |
| confirm | No | Required when safe mode is enabled |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does add useful context beyond the schema — the MCP allowlist requirement and safe-mode confirmation behavior — but does not disclose the side effects of plugin activation (activation hooks, potential site instability) or what happens on success/failure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero wasted words: purpose plus example in the first sentence, constraints in the second. Front-loaded with the core action, and every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple two-parameter tool with schemas that fully document the params, but there is no output schema or annotations to compensate. Missing disclosure of activation side effects, the meaning of safe mode, and expected return behavior leaves notable gaps for an agent deciding whether this mutation is safe to invoke.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters. The description adds a concrete slug example and reiterates the confirm-in-safe-mode rule, which is marginal value beyond the schema — consistent with the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (activate), resource (plugin), and method (by slug) with a concrete example (litespeed-cache/litespeed-cache.php). The purpose is unambiguous and inherently distinguished from the sibling wp_deactivate_plugin and listing tools like wp_list_plugins.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear usage prerequisites: the plugin slug must be on the MCP allowlist, and confirm is mandatory in safe mode. It gives actionable conditions for calling the tool, though it does not explicitly name alternatives or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add an admin or customer-visible note to a WooCommerce order
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Order ID | |
| note | Yes | Note text | |
| customer_note | No | Make note visible to customer |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It states that the note can be admin-visible or customer-visible, but it does not explain side effects, whether the note is appended to order history, permission requirements, or what happens if the order does not exist. This is minimal for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tightly written sentence with no filler or redundant information. It front-loads the action and the core distinction, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and the schema covers all parameters, but there is no output schema and no annotations. The description explains the core purpose and visibility nuance, yet it omits expected return behavior or error conditions. It is minimally viable but leaves some operational context to inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all three parameters with 100% coverage, so the description does not need to repeat them. The phrase 'admin or customer-visible' adds a small amount of semantic context for the customer_note parameter, but the description does not otherwise deepen parameter understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Add'), the resource ('note to a WooCommerce order'), and the key distinction of admin versus customer-visible notes. It is unambiguous and differentiates this tool from related order tools like wp_get_order or wp_update_order.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used when you need to add a note to an order, but it provides no explicit guidance on when to choose this tool over alternatives, nor does it mention prerequisites such as the order existing. No when-not-to-use context is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run SEO audit across published content (missing titles, descriptions, etc.)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful scoping (published content only) and examples of checks performed, but it does not disclose whether the operation is read-only, what the result/report format looks like, whether anything is modified, or any side effects. For a tool with zero annotation coverage, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with zero wasted words. The verb is front-loaded, the scope follows immediately, and the parenthetical gives concrete examples of what the audit inspects. Appropriate length for a no-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema audit tool, the description covers the core purpose, the scope of content examined, and the kinds of issues detected. The only gap is that without an output schema, the agent gets no hint about what the audit returns, but the overall simplicity of the tool limits the impact of that omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, which gives a baseline of 4 per the rubric. There is nothing for the description to clarify about arguments, and the schema is trivially complete at 100% coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description has a specific verb ('Run'), a specific resource ('SEO audit'), and a clear scope ('across published content') with concrete examples of what it checks ('missing titles, descriptions'). This distinguishes it from per-page SEO tools like wp_get_page_seo and broader tools like wp_site_audit, though it does not name those siblings explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: run this to get an SEO overview across all published content. However, it does not explicitly state when to choose this over alternatives such as wp_get_page_seo (single-page SEO) or wp_site_audit (whole-site audit), nor does it give any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute multiple WP MCP operations in a single request (max 20)
| Name | Required | Description | Default |
|---|---|---|---|
| operations | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only mentions a max of 20 operations, but omits critical behavioral details such as execution order, atomicity, error handling, or authentication requirements for a batch tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words, conveying the essential purpose efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex batch tool, the description lacks crucial context such as return format (e.g., results per operation), error behavior, and ordering. With no output schema, the description should provide more completeness but fails to do so.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema itself defines the operations parameter with method enum, path, and optional body, providing most meaning. The description adds no additional parameter context, so the baseline of 3 is appropriate given minimal description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool executes multiple WP MCP operations in a single request with a maximum of 20, distinguishing it from the many single-operation siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for batching multiple operations but does not explicitly state when to use this tool versus individual tools, nor does it mention any exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a WordPress category
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| slug | No | ||
| parent | No | ||
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits but only says 'Create a WordPress category.' It does not mention whether it overwrites existing categories, requires permissions, or handles duplicates, leaving the agent uninformed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, making it concise but too minimal for a tool with 4 parameters and no output schema. It could be expanded without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multiple parameters, no output schema, many siblings), the description is incomplete. It lacks information on return values, parameter usage, and when to use it, making it insufficient for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should explain parameters. However, it provides no meaning beyond the schema, e.g., what 'slug' or 'parent' mean or their constraints, failing to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('WordPress category'), which is specific and distinguishes it from sibling tools like wp_create_tag or wp_create_page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as wp_create_tag for tags or wp_update_category for modifications. No context on prerequisites or conditions is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new item in a custom post type
| Name | Required | Description | Default |
|---|---|---|---|
| meta | No | ||
| slug | No | ||
| title | Yes | ||
| parent | No | ||
| status | No | ||
| content | No | ||
| excerpt | No | ||
| post_type | Yes | ||
| featured_media | No | ||
| scheduled_date | No | ISO or parseable date string to schedule publication |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says the tool creates an item, without mentioning permissions, default status behavior, validation, duplicate handling, or any side effects, leaving significant behavioral uncertainty for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no filler, but for a tool with 10 parameters and sparse schema documentation, this is under-specification rather than effective conciseness. It front-loads the core purpose but fails to carry the weight the definition needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 10 parameters, no output schema, no annotations, and only 10% schema description coverage, a one-line high-level description is far from complete. An agent would still lack essential context about required inputs, behavior, defaults, and what the tool returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema description coverage is only 10%, and the tool description adds no parameter-level meaning. It does not explain the required post_type and title fields, the meta object, status options, or scheduled_date semantics beyond what property names or one schema description already provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (create) and the resource (an item in a custom post type), which aligns with the tool name. It is distinguishable from sibling tools like wp_create_post and wp_create_page via the 'custom post type' qualifier, though it does not explicitly name or contrast those alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus alternatives such as wp_create_post, wp_create_page, or wp_create_taxonomy_term. The description only states what the tool does, with no context about prerequisites, exclusions, or preferred use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a custom MCP outbound webhook. Secret is returned once on create. confirm:true required when safe mode is on.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | HTTPS delivery URL | |
| name | Yes | Webhook name | |
| topics | Yes | Event topics to subscribe to | |
| confirm | No | Required when safe mode is enabled | |
| enabled | No | Enable webhook (default true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does contribute one genuinely useful behavior: 'Secret is returned once on create,' which warns the agent to capture it immediately. But the confirm requirement merely restates the schema's own confirm description, and other creation behaviors (idempotency, failure modes, what happens in safe mode without confirm) are not disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with zero filler, front-loaded with the primary action, and both sentences carry operational value (what it does, what to preserve, what to pass in safe mode). No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The core create action, a key return-value fact (secret shown once), and a precondition (safe mode confirm) are covered. But there is no output schema and no annotations, so more context is warranted: the full response shape, how to discover valid topics (sibling wp_list_webhook_topics exists), and error/edge cases are absent. Adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds the secret-returned-once behavior, which concerns the operation's result rather than parameters, and restates the confirm condition already present in the schema. It does not add deeper per-parameter semantics such as topic format or URL validation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Create') and a specific resource ('custom MCP outbound webhook'), which distinguishes it from sibling tools like wp_create_form_webhook and wp_create_woocommerce_webhook via the 'custom' and 'MCP outbound' qualifiers. It does not explicitly contrast with those siblings, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The safe-mode condition ('confirm:true required when safe mode is on') gives a concrete precondition, and the secret-once note implies this is the right tool when a fresh secret is needed. However, no alternatives are named and there is no explicit guidance on when to choose this over form or WooCommerce webhook creates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a Ninja Forms webhook action on a form
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Webhook URL | |
| label | No | ||
| active | No | ||
| method | No | HTTP method (default POST) | |
| form_id | Yes | Ninja Form ID | |
| headers | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, but it only states the bare action. It does not disclose whether the webhook is active by default, whether creating is idempotent or creates duplicates, what happens if the form_id doesn't exist, whether the URL is validated, or what side effects occur. For a mutation tool this is a significant transparency gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no filler, front-loaded with the verb. It is efficiently written, though it earns its conciseness by sacrificing substantive content that other dimensions needed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with 6 parameters, a nested headers object, no annotations, and no output schema, the description is too sparse. The agent is left without knowledge of the return value, default behaviors, or how this tool relates to the large cluster of sibling webhook tools (list/update/delete form, custom, WooCommerce).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50% — label, active, and headers have no schema descriptions. The description adds nothing about these undocumented parameters, nor does it clarify the relationship between form_id and the form targeted, or the behavior of the nested headers object. It fails to compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Create'), a specific resource ('Ninja Forms webhook action'), and a target ('on a form'), which clearly states what the tool does. The 'Ninja Forms' qualifier helps differentiate it from wp_create_custom_webhook and wp_create_woocommerce_webhook, though it does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus siblings like wp_update_form_webhook, wp_delete_form_webhook, wp_list_form_webhooks, or the custom webhook tools. The agent must infer from the name alone that this is the create variant, with no context about prerequisites (e.g., form must exist) or scenarios where another webhook tool is more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a landing page with structured sections (hero, services, testimonials, FAQ, CTA)
| Name | Required | Description | Default |
|---|---|---|---|
| slug | No | ||
| title | Yes | Page title | |
| status | No | draft | |
| sections | Yes | Page sections to compose |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden for behavioral disclosure. It only says 'create', implying a write operation, but fails to disclose important traits such as whether duplicates are checked, what happens on conflict, authentication needs, or side effects like modifications to other entities.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It front-loads the core action ('Create a landing page') and lists the section types efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 parameters, nested array for sections, no output schema, no annotations), the description is too brief. It does not explain return values, error conditions, or how the sections parameter is used. More detail is needed for an agent to invoke it correctly without additional knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (title and sections have descriptions, slug and status do not). The description does not add any parameter-level meaning beyond the schema, failing to clarify slug rules or status options. It does not compensate for the undocumented parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a landing page with specific structured sections (hero, services, testimonials, FAQ, CTA), which distinguishes it from generic page/post creation tools like wp_create_page and wp_create_post. The verb 'create' and resource 'landing page' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like wp_create_page. There is no mention of prerequisites, exclusions, or context that helps an agent decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new WordPress page
| Name | Required | Description | Default |
|---|---|---|---|
| meta | No | ||
| slug | No | ||
| title | Yes | Page title | |
| parent | No | ||
| status | No | draft | |
| content | No | HTML or Gutenberg block content | |
| excerpt | No | ||
| template | No | ||
| featured_media | No | ||
| scheduled_date | No | ISO or parseable date string to schedule publication |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure, but it only says 'create.' It does not mention the default 'draft' status, whether scheduling via scheduled_date is supported, what happens with content format, or any required permissions/side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The sentence is short and front-loaded with the key action, which is efficient. However, given the tool's 10 parameters and lack of annotations, the description is under-sized rather than appropriately sized for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 10 parameters, no annotations, and no output schema, yet the description offers only a minimal action statement. Missing critical context includes the default status, scheduling behavior, content expectations, and relationships with sibling page/post tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 30%, and the description adds no parameter meaning beyond what the schema already provides. Ten parameters exist, but the description explains none of them, so an agent would have to rely entirely on the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (create) and resource (WordPress page), so an agent knows the core operation. However, it does not differentiate this tool from siblings like wp_create_post or wp_create_landing_page, which could create similar content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool versus alternatives such as wp_create_post, wp_create_landing_page, or wp_elementor_create_blank_page. The description implies usage for creating pages but provides no exclusions or selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new WordPress post
| Name | Required | Description | Default |
|---|---|---|---|
| meta | No | ||
| slug | No | ||
| tags | No | ||
| title | Yes | ||
| status | No | draft | |
| sticky | No | ||
| content | No | ||
| excerpt | No | ||
| categories | No | ||
| featured_media | No | ||
| scheduled_date | No | ISO or parseable date string to schedule publication |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description carries the full burden of behavioral disclosure. It only states the basic creation action and does not explain side effects, publishing behavior, status defaults, required fields, or what the response will contain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise and front-loaded with the core action. However, for a tool with 11 parameters and no annotations, the brevity borders on under-specification rather than efficient completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex creation tool with 11 parameters, no annotations, and no output schema, yet the description is a single generic sentence. An agent has almost no contextual information about required inputs, valid values, or expected output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 9%, so the description must compensate for the 11 parameters, but it adds no parameter-level meaning. It does not clarify the required title, status defaults, content format, categories, tags, scheduling, or any other input semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Create') with a clear resource ('a new WordPress post'). This cleanly distinguishes it from sibling tools like wp_create_page, wp_create_product, and other creation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus the many sibling creation tools. It does not mention alternatives, exclusions, or conditions such as creating pages versus posts versus custom post types.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new WooCommerce simple product
| Name | Required | Description | Default |
|---|---|---|---|
| sku | No | ||
| name | Yes | Product name | |
| slug | No | ||
| status | No | ||
| featured | No | ||
| sale_price | No | ||
| description | No | ||
| manage_stock | No | ||
| stock_status | No | ||
| regular_price | No | ||
| stock_quantity | No | ||
| short_description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, and it only states the creation action. It does not disclose default status (draft vs. published), uniqueness constraints on sku, whether duplicate names/skus are rejected, side effects on stock or inventory, or what the response contains. For a mutation tool with zero annotation coverage, this is a significant transparency gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The single sentence contains zero wasted words and front-loads the core purpose, which is good. However, for a 12-parameter tool with no annotations and no output schema, a 7-word description is under-specified rather than appropriately sized — conciseness here crosses into insufficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (12 parameters, 8% schema coverage, no annotations, no output schema), a one-sentence description is radically incomplete. The agent would need external knowledge to correctly construct a product payload, understand pricing/stock field interplay, and anticipate the tool's response. Nothing beyond the basic operation is conveyed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 8% — only 'name' is documented in the schema, leaving 11 of 12 parameters (sku, status, sale_price, manage_stock, stock_status, regular_price, stock_quantity, etc.) completely unexplained. The description adds nothing about parameters, so it fails to compensate for the near-total absence of schema descriptions. An agent has no way to know what values are valid for fields like stock_status or status.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new WooCommerce simple product' names a specific verb (create), a specific resource (WooCommerce simple product), and even qualifies the product type, which distinguishes it from generic siblings like wp_create_post and wp_create_cpt_item. It is clear enough for an agent to identify what this tool does, though it does not explicitly contrast itself with the many other create tools in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as wp_create_post, wp_update_product, or wp_create_cpt_item. No context about product-type constraints (simple vs. variable products), prerequisites like WooCommerce being active, or scenarios where a different sibling would be more appropriate. The agent must infer usage entirely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a URL redirect
| Name | Required | Description | Default |
|---|---|---|---|
| enabled | No | ||
| target_url | Yes | Target URL | |
| source_path | Yes | Source path e.g. /old-page | |
| status_code | No | 301 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must disclose behavioral traits. It only states 'create', with no details on side effects, permissions, or error conditions. This is insufficient for a write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, no redundancy, and quickly conveys the core action. Highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 4 parameters, no output schema, and no annotations, the description is too brief to provide complete context. Missing usage context, behavioral details, and parameter elaboration.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool description adds no parameter information. With only 50% schema description coverage, the description should compensate, but it does not address parameter meanings or constraints beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'create' and the resource 'URL redirect', making the tool's purpose evident. However, it does not differentiate from other creation tools like wp_create_page or wp_create_post beyond the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as wp_update_redirect or wp_delete_redirect. Missing prerequisites or context for creation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a WordPress tag
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| slug | No | ||
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only states 'create' without detailing side effects, permissions, error handling, or success behavior. Minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, making it concise. However, it is so brief that it sacrifices necessary detail, hitting the lower bound of acceptable conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given three parameters with no schema descriptions and no output schema, the description fails to provide essential context like return values, error conditions, or parameter formatting. It is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no descriptions, and the tool description adds no meaning to the parameters. For three parameters (name, slug, description), there is no explanation of their roles or constraints (e.g., slug formatting). This is a critical gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (create) and resource (WordPress tag). It is unambiguous, though it could be more specific about the purpose within the context of siblings like wp_update_tag or wp_delete_tag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., wp_update_tag for existing tags). The description lacks context for selection among sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a term in a taxonomy
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| slug | No | ||
| parent | No | Parent term ID (categories only) | |
| taxonomy | Yes | ||
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, but it only states the mutation. It does not explain behavior on duplicate terms, whether slug is auto-generated, permission requirements, or how parent/child relationships are handled, leaving significant behavioral unknowns.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words, making it easy to parse. It is under-specified, but the conciseness itself is appropriate for such a brief statement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given five parameters, no annotations, and no output schema, the description is too sparse to fully support correct invocation. It omits how taxonomy should be specified, how this relates to category/tag creation tools, and what happens after creation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20%, and the tool description adds no parameter-level meaning. The parent parameter is explained in the schema, but taxonomy, name, slug, and description are left to the agent to infer from their names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a clear verb ('Create') and a specific resource ('a term in a taxonomy'), so an agent understands the basic action. However, it does not differentiate this from sibling tools like wp_create_category and wp_create_tag, which also create taxonomy terms in WordPress, leaving some ambiguity about scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool versus alternatives such as wp_create_category or wp_create_tag. The description does not mention custom taxonomies, built-in taxonomy handling, or any conditions that would make this tool the preferred choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a WordPress user. confirm:true required in safe mode. Administrator role requires explicit confirm.
| Name | Required | Description | Default |
|---|---|---|---|
| role | No | author | |
| Yes | |||
| confirm | No | Required when safe mode is enabled | |
| password | No | Auto-generated if omitted | |
| username | Yes | ||
| display_name | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It does disclose an important safety behavior: safe mode requires confirm:true, and administrator role requires explicit confirm. However, it does not disclose side effects, permissions, email notifications, password generation behavior, or response format, leaving significant behavioral context unstated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise: two sentences, front-loaded with the core action followed by the most safety-relevant requirements. Every sentence contributes actionable information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter create operation with no annotations and no output schema, this description is too sparse. It omits the expected return value, side effects, duplicate handling, email notification behavior, and any guidance on the password parameter beyond what the schema already states.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%, and the description only adds one meaningful semantic fact beyond the schema: the administrator role requires explicit confirm. It does not explain username, email, display_name, or role semantics beyond what the schema already provides, so it fails to compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Create a WordPress user.' This clearly distinguishes it from user read tools like wp_get_user and wp_list_users, as well as from the many other create_* siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides operational prerequisites ('confirm:true required in safe mode') but gives no guidance on when to prefer this tool over alternatives or when not to use it. The safe-mode note implies usage context, but no exclusions or alternative routing are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a WooCommerce native webhook. Secret returned once. confirm:true required when safe mode is on.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Webhook name | |
| topic | Yes | WC topic e.g. order.created, order.updated, product.created | |
| status | No | ||
| confirm | No | Required when safe mode is enabled | |
| delivery_url | Yes | Delivery URL |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and it delivers two non-obvious facts: 'Secret returned once' warns the agent the credential is unrecoverable after creation, and confirm:true being required in safe mode flags a conditional execution barrier. It doesn't cover response structure or permissions, but the highest-risk behaviors are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with zero filler: the core action is front-loaded, followed by the one-time-security warning and the conditional requirement. Every sentence earns its place, though the confirm sentence partially duplicates the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating tool with no annotations and no output schema, it covers the two operational must-knows (one-time secret, safe-mode confirmation) but doesn't state what the response contains beyond the secret or how to subsequently locate the webhook (wp_list_woocommerce_webhooks). The 'safe mode' concept is referenced without explanation, but the critical call-time behaviors are present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80%, so the schema is doing most of the work; the description only reinforces the confirm parameter's safe-mode requirement already stated in the schema ('Required when safe mode is enabled'). It adds no new per-parameter detail beyond what structured fields provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Create a WooCommerce native webhook') that distinguishes it from sibling creation tools like wp_create_custom_webhook and wp_create_form_webhook. The qualifier 'native' precisely scopes the resource type, so an agent can tell this apart from other webhook-creation siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'WooCommerce native' qualifier implies the domain for this tool, but there is no explicit when-to-use or when-not-to-use guidance. It never names the alternative (e.g., wp_create_custom_webhook for non-native workflows) nor states the condition that selects between them, leaving the choice to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deactivate a plugin by slug. confirm:true required when safe mode is enabled.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Plugin file path relative to wp-content/plugins/ | |
| confirm | No | Required when safe mode is enabled |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. 'Deactivate' makes the state-changing nature clear and the safe-mode confirm note is a genuinely useful operational detail, but consequences, reversibility, permission requirements, and error behavior are never mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with zero redundancy. The core action is front-loaded in the first sentence and the only non-obvious invocation detail is appended second.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter state-change tool, the description covers the essential action and highlights the one operational trap (safe mode confirm requirement). There is no output schema to clarify return values, but the outcome of a deactivation is largely self-evident, so the gap is minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description's reference to slug and confirm:true merely mirrors what the schema already states ('Plugin file path relative to wp-content/plugins/', 'Required when safe mode is enabled') without adding new format, default, or edge-case detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Deactivate a plugin by slug' pairs a specific verb with a specific resource and states the identification mechanism. It is immediately distinguishable from the inverse sibling wp_activate_plugin and from read-only siblings like wp_list_plugins, even without reading schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Aside from the safe-mode confirm prerequisite, there is no guidance on when to select this tool over alternatives. The description never names wp_activate_plugin as the inverse operation or suggests when deactivation is appropriate, so an agent gets no routing help among the large sibling set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a WordPress category
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| confirm | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only says 'Delete', implying a destructive action, but does not elaborate on side effects (e.g., handling of assigned posts), permanence, or the need for confirmation. With no annotations, the description fails to disclose important behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
While very concise (one sentence), the description is underspecified, sacrificing necessary details. It does not earn its place as it provides minimal value over the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a delete operation with two required parameters and no output schema, the description is severely lacking. It omits return value, error conditions, and behavior related to the confirm parameter, making it incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no meaning to the parameters. It does not explain that 'id' is the category ID or that 'confirm' is a safety flag. The agent must infer solely from parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a WordPress category' clearly states the verb and resource. It distinguishes from sibling delete tools (e.g., wp_delete_post, wp_delete_tag) by specifying the target is a category.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like wp_update_category or wp_create_category. No prerequisites or conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a custom post type item (moves to trash by default)
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| force | No | Permanently delete instead of trash | |
| confirm | Yes | Must be true to confirm deletion | |
| post_type | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals the useful default ('moves to trash by default') but omits that force permanently deletes, that confirm is required, and that permanent deletion is irreversible. For a destructive tool, this is a significant transparency gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short sentence with no filler, and the most decision-relevant detail — the default trash behavior — is front-loaded. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a destructive action with no annotations, no output schema, and 4 parameters (half undocumented), the description is too minimal. It omits expected behavior for `force`, the confirmation requirement, return values, error conditions, and any permissions or side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50%, so the description must compensate for undocumented parameters. It adds meaning only by clarifying the default trash behavior, which relates to the `force` parameter already described in the schema. It provides no additional semantics for `post_type` or `id` and does not reinforce that `confirm` must be true.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Delete') and resource ('custom post type item') and adds the default trash behavior, which is clear and distinguishes it from standard post deletion tools like wp_delete_post. However, it does not explicitly name a sibling alternative or contrast its scope, so it falls just short of a full 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for custom post type items rather than regular posts, pages, or media, which gives some context. But it provides no explicit guidance on when to prefer this over wp_delete_post, wp_delete_page, or other deletion tools, and no exclusions or prerequisites are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a custom MCP webhook. confirm:true required when safe mode is on.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Webhook ID | |
| confirm | No | Required when safe mode is enabled |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It does convey that this is a destructive action and notes the safe-mode confirmation requirement, but it does not mention irreversibility, permissions, or what happens after deletion.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, focused sentences: the first states the action and resource, the second provides the critical confirmation condition. No filler or redundant elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity delete tool with fully described parameters, the description plus schema provides enough information to invoke it correctly. The only minor gap is that it does not explain how an agent can determine whether safe mode is on, but this is not a blocker.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents both parameters with 100% coverage. The description essentially restates the confirm behavior already present in the schema and adds no new parameter-level meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action ('Delete') and the specific resource ('custom MCP webhook'), making it clear what the tool does. It is also distinguishable from sibling tools like wp_delete_form_webhook and wp_delete_woocommerce_webhook.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly scopes the tool to custom MCP webhooks and adds an important operational condition about confirm:true in safe mode. It does not explicitly name alternative tools or exclusion cases, so it stops short of a perfect usage-routing score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a Ninja Forms webhook action
| Name | Required | Description | Default |
|---|---|---|---|
| form_id | Yes | Ninja Form ID | |
| action_id | Yes | Webhook action ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing the destructive nature of the tool. It does clearly say 'Delete', which signals that the webhook action will be removed, but it adds little beyond that: no mention of irreversibility, cascading effects on the form, cached data, or response behavior. It is honest but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, direct sentence with no filler or redundancy. The core action and resource are front-loaded, making it instantly scannable for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter delete operation, the description and complete schema cover the minimum needed to invoke the tool. However, with no annotations and no output schema, the description omits any indication of success/failure behavior or side effects, which leaves a moderate gap for a destructive operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters ('Ninja Form ID' and 'Webhook action ID'). The description does not add any additional meaning or clarify parameter relationships, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Delete') and a specific resource ('Ninja Forms webhook action'), clearly identifying the operation. It does not explicitly reference sibling tools like wp_update_form_webhook or wp_list_form_webhooks, but the destructive verb inherently distinguishes it from create/update/list operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives, no prerequisites are mentioned, and there are no exclusions or context cues beyond the obvious 'delete this resource' implication. The description simply states the action without any decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a media item (moves to trash by default)
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| force | No | ||
| confirm | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses default behavior (moves to trash), but lacks details on force parameter, permanence, permissions, or side effects. With zero annotations, more behavioral context is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise and front-loaded, but too sparse given the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Missing return value, error cases, and parameter details. Incomplete for a deletion tool with 3 parameters and no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and description adds no meaning for id, force, or confirm parameters. Agent must infer from names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States verb 'Delete' and specific resource 'media item', clearly distinguishing from sibling tools like wp_delete_post or wp_delete_page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use vs alternatives, no prerequisites or when-not-to-use information provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a WordPress page (moves to trash by default)
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Page ID | |
| force | No | Permanently delete instead of trash | |
| confirm | Yes | Must be true to confirm deletion |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description adds some behavioral context (default trash behavior, force for permanent delete). However, it omits details on side effects, required permissions, or confirmation requirement beyond schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that conveys core purpose and a key behavioral detail. No unnecessary words; efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description covers the essential operation and default behavior. Lacks explicit mention of required confirm field (though schema specifies it). Otherwise adequate for a simple deletion tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and description adds no parameter-specific details beyond what's in the schema. Baseline score of 3 is appropriate as the schema already documents all parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Delete', the resource 'WordPress page', and a key behavioral detail 'moves to trash by default'. It distinguishes from siblings like wp_delete_post.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives (e.g., wp_delete_post). The description implies use for pages but lacks when-not or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a WordPress post (moves to trash by default)
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| force | No | ||
| confirm | Yes | Must be true to confirm deletion |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must cover behavior. It mentions default trash behavior but does not explain what force=true does (e.g., permanent delete), return values, or error handling. This leaves significant gaps for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no superfluous words. It is efficiently front-loaded with the key action and default behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 parameters (2 required), no output schema, and no annotations. The description lacks information on error conditions, permissions, and what the return value indicates. For a deletion tool, this is insufficient for safe and correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (confirm has description). The description adds context about trash behavior, which relates to force, but does not explain id or force semantics in detail. With low coverage, description partially compensates but not fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a WordPress post' with a specific verb and resource. It also notes the default behavior (moves to trash), which distinguishes it from sibling tools like wp_delete_page or wp_delete_tag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description hints at default behavior (trash) but does not explicitly state when to use vs alternatives like wp_batch_operations or when to set force=true. No guidance on prerequisites or permissions is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a WooCommerce product (moves to trash by default)
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| force | No | ||
| confirm | Yes | Must be true to confirm deletion |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of disclosing behavioral side effects. It does disclose the key default behavior—moves to trash—which signals a recoverable delete, but it does not explain what force=true does, whether the deletion can be permanent, or any permission or irreversibility concerns.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The definition is a single, front-loaded sentence with no filler. The parenthetical about trash behavior is high-value information that earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with three parameters, no annotations, and no output schema, the description is incomplete. It omits the effect of force, avoids synthesizing the confirmation requirement into the operation, and gives no sense of what happens after deletion beyond the default trash behavior. The trash detail is helpful, but an agent still lacks enough context to safely reason about permanent deletion.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%, with only 'confirm' documented and 'id' and 'force' left bare. The description adds only an indirect hint that trash is the default behavior, which relates weakly to 'force', but it does not clarify the id parameter or the interaction between confirm and force. It fails to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the specific verb ('Delete') and resource ('a WooCommerce product'), making it clearly distinct from sibling delete tools like wp_delete_post or wp_delete_page. The parenthetical about moving to trash adds a useful scoping detail rather than restating the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used when a WooCommerce product needs to be deleted, but it gives no explicit guidance on when to prefer it over related tools or what conditions must be met. It does not mention alternatives or exclusions, leaving usage mostly inferred from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a redirect
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| confirm | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description 'Delete a redirect' implies a destructive action but offers no details on reversibility, permissions, or side effects. The confirm parameter is not acknowledged, leaving the agent unaware of the safety mechanism.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short but at the expense of completeness. It lacks any structure or front-loading of critical information, making it closer to underspecification than effective conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and output schema, the description should fully explain the tool's behavior and parameters. It fails to do so, omitting the mandatory confirm parameter and any return value details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description fails to explain the 'id' and 'confirm' parameters. It provides no value beyond the schema itself, leaving the agent to guess their purpose and constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a redirect' clearly states the verb and resource, and distinguishes it from sibling tools like wp_delete_post or wp_delete_page. However, it lacks any additional context about the scope or specific redirect type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance provided. The description does not mention when to use this tool over alternatives (e.g., wp_update_redirect or wp_list_redirects) or any prerequisites like needing the id or confirm parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a WordPress tag
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| confirm | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full burden of disclosing behavioral traits. It does not state that the tool permanently destroys a tag, mention required permissions, or describe effects on associated posts. A deletion tool should clearly communicate its irrevocable nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that merely repeats the tool's name in plain English. It is under-specified rather than concise, wasting the opportunity to add value. Every sentence should earn its place; this one does not.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple deletion tool with two required parameters and no output schema, the description is incomplete. It omits essential context such as the need for a valid tag ID, the destructive nature, and any confirmation requirements, leaving significant gaps for agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has two required parameters (id and confirm) with 0% schema description coverage, yet the description provides no explanation of their meaning or usage. It fails to explain that 'id' is the tag ID and 'confirm' must be boolean true to proceed, leaving agents to guess.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a WordPress tag' is essentially a tautology of the tool name 'wp_delete_tag', adding no new information. It does not specify any unique scope or behavior that distinguishes it from other deletion tools like wp_delete_category or wp_delete_post.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., when to delete a tag vs. update or create). There is no mention of prerequisites, contexts, or the need for confirmation, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a WooCommerce native webhook. confirm:true required when safe mode is on.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | WooCommerce webhook ID | |
| confirm | No | Required when safe mode is enabled |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full burden of behavioral disclosure. It clearly indicates a destructive delete operation and adds the safe-mode confirmation requirement, which is valuable. However, it does not mention permanence, permissions, or what happens on success or failure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences with no filler. It states the purpose upfront and then adds the key operational caveat. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter delete operation, the description plus schema are largely sufficient. However, with no annotations, it could be more complete by noting that deletion is permanent or what happens in non-safe-mode when confirm is absent. The lack of an output schema does not hurt because the return value is not critical for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters are already documented in the schema. The description adds no new semantic detail beyond restating confirm's condition, which the schema lists as 'required when safe mode is enabled.' The baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource, 'Delete a WooCommerce native webhook,' and the word 'native' helps distinguish it from sibling tools like wp_delete_custom_webhook and wp_delete_form_webhook. It is clear enough for an agent to identify the intended operation without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied by the tool name and the 'native' descriptor, but the description does not explicitly state when to use this tool versus alternatives. The note about confirm being required in safe mode is a useful conditional, but there is no guidance for other scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Append a new item to an Elementor repeater widget (add a carousel slide, testimonial, photo). Provide item fields matching the widget schema.
| Name | Required | Description | Default |
|---|---|---|---|
| item | Yes | Item fields — for image-carousel: {image: {id: 42, url: '...'}, caption: 'text', link: {url: ''}}; for jet-testimonials: {item_name: 'Name', item_title: 'Title', item_content: 'Text', item_image: {id: 42}} | |
| page_id | Yes | Page or template ID | |
| element_id | Yes | Element ID from wp_elementor_list_elements |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden. It conveys that the operation is additive ('append', 'add a...') rather than destructive to existing items, and it flags a real behavioral constraint: item fields must match the widget schema. It does not disclose return values, persistence or CSS-regeneration side effects, or behavior when element_id does not reference a repeater widget — gaps that matter for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One front-loaded sentence states the action before concrete examples, followed by a short operational directive. There is no filler and both clauses earn their place, making the definition appropriately sized for its scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a nested flexible object, no output schema, and no annotations, so completeness depends on the description plus the parameter schema. Together they provide the key operational steps (target page, element_id from wp_elementor_list_elements, schema-matching fields), but the return value and side effects of the mutation are left unstated. That is adequate for making the call but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the item parameter itself already carries rich per-widget field examples (image-carousel, jet-testimonials) plus page_id and element_id semantics. The description's 'provide item fields matching the widget schema' reinforces but does not extend the schema's guidance, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource pair ('Append a new item to an Elementor repeater widget') and grounds it with concrete examples (carousel slide, testimonial, photo). The 'append' verb clearly differentiates it from wp_elementor_update_repeater_item and wp_elementor_remove_repeater_item, and from wp_elementor_insert_widget which adds whole widgets rather than items within them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The examples ('add a carousel slide, testimonial, photo') give an agent concrete context for when this tool applies, and the directive to 'provide item fields matching the widget schema' sets operational expectations for the call. It does not, however, name alternatives or state when not to use it (e.g., versus wp_elementor_update_repeater_item for modifying an existing slide), so it stops short of explicit routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove all Elementor canvas sections/containers from a page for rebuilds. Theme builder header/footer templates are unaffected. confirm:true required when safe mode is on.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No | ||
| page_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a destructive action ('remove all sections/containers'), which is essential behavioral context. It also mentions the confirm:true requirement under safe mode. However, with no annotations, it leaves scope gaps: no mention of page_id validation, whether content is recoverable, or what happens if the page has no Elementor data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no fluff. The core action and scope are front-loaded, and the safety requirement is stated compactly at the end.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description covers the destructive nature and the confirm requirement, which are the most critical facts. It is slightly thin on safe-mode behavior, prerequisites for the tool to work, and what happens to Elementor data from theme templates, but the core call guidance is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it partially does: it explains the confirm parameter's role ('confirm:true required when safe mode is on'). However, it does not explain semantics of page_id beyond the schema's name, or whether confirm must also be true when safe mode is off.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('remove'), a resource ('Elementor canvas sections/containers'), and the intent ('for rebuilds'). It explicitly distinguishes what is unaffected ('theme builder header/footer templates'), which separates it from the broader Elementor toolset.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly communicates when to use it: when clearing a page's Elementor canvas for a rebuild. It doesn't explicitly name sibling alternatives or when-not-to-use conditions, but the 'Theme builder header/footer templates are unaffected' line provides useful exclusion context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Clone a widget, section, or container subtree with new IDs. confirm:true required when safe mode is on.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No | ||
| page_id | Yes | ||
| element_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It indicates that cloning produces new IDs and that confirm is needed in safe mode, implying a potentially destructive action when safe mode is off. However, it does not disclose permission requirements, reversibility, side effects (e.g., whether the cloned element is inserted inline or appended), or what happens to the original element.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (two sentences, 18 words) and front-loaded with the primary action. Every word serves a purpose, adding key information about IDs and the confirm requirement. It wastes no space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (cloning with three parameters, no output schema), the description is incomplete. It does not explain what the tool returns or the expected state after cloning (e.g., does it return the new element ID?). The parameter descriptions are missing, and the behavioral transparency is low. The description leaves significant gaps for an AI agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, and the description only adds meaning for the 'confirm' parameter (required when safe mode is on). The 'page_id' and 'element_id' parameters are not elaborated upon; their purpose must be inferred from the tool name and context. This is insufficient for an AI agent to understand how to correctly specify these parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (clone) and the resource (widget, section, or container subtree), and specifies that new IDs are generated. This distinguishes it from sibling tools like wp_elementor_duplicate_page (duplicate entire page) and wp_elementor_insert_section (insert new).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions that 'confirm:true' is required when safe mode is on, providing some guidance on when to set the confirm parameter. However, it does not explicitly state when to use this tool versus alternatives (e.g., when to clone vs duplicate a page or insert a new element), nor does it list prerequisites or constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new Elementor page with an empty canvas and header/footer template (elementor_header_footer by default). confirm:true required when safe mode is on.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | No | ||
| title | Yes | Page title | |
| status | No | draft | |
| confirm | No | ||
| template | No | WordPress page template slug | elementor_header_footer |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral disclosure burden. It usefully reveals the safe-mode confirm requirement and the default template, but it does not explain permissions, side effects, or what response is returned. This is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence: the action is stated first, then the default template, then the one critical precondition. There is no filler or redundant repetition of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create operation, the description covers the core behavior and the non-obvious safe-mode condition. However, with no annotations and no output schema, it leaves gaps around permissions, return values, and how this relates to generic wp_create_page or Elementor-specific siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 40%, so the description needed to compensate. It clarifies the template parameter as header/footer template and confirms the confirm parameter's role in safe mode, but it adds no meaning for slug or status beyond the schema's minimal representation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: create a new Elementor page. It adds distinctive details—empty canvas and default elementor_header_footer template—that set it apart from generic page creation and landing page tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates when to use the tool: when a blank Elementor page with a header/footer template is needed. It also gives a concrete precondition, confirm:true required when safe mode is on. It does not explicitly name alternatives or exclusions, so it is not a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Duplicate an Elementor page as a new draft with remapped element IDs. Preserves heading text through safe JSON pipeline. confirm:true required when safe mode is on.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | No | ||
| title | No | ||
| status | No | draft | |
| confirm | No | ||
| source_id | Yes | Source page ID to clone |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry behavioral context. It does disclose remapping of element IDs, preservation of heading text, and the confirm requirement. However, it does not state whether the original page is left untouched, what 'safe mode' means, or what the operation returns.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with no redundancy. The primary action and key constraint are front-loaded, and every sentence adds relevant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and low schema coverage, the description leaves safe mode, slug, title, and status undefined. It also omits side effects and return behavior, making it too incomplete for fully correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20% (source_id). The description adds meaning for confirm ('required when safe mode is on') but leaves slug, title, and status unexplained, failing to compensate for the sparse schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('Duplicate an Elementor page as a new draft') and a distinctive technical detail ('with remapped element IDs'). This differentiates it from siblings like wp_elementor_clone_element or wp_create_page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as wp_create_page, wp_update_page, or wp_elementor_clone_element. The only operational note is 'confirm:true required when safe mode is on', which is a prerequisite, not a usage routing rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find a suitable parent column or container element ID for inserting widgets on an Elementor page
| Name | Required | Description | Default |
|---|---|---|---|
| page_id | Yes | WordPress page ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full disclosure burden. It does not state whether the operation is read-only, how suitability is determined, what happens when no parent exists, or whether it returns one ID or multiple candidates. The verb 'Find' implies non-mutating behavior, but that is not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It states what the tool does and the context for use economically.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a simple one-parameter interface, but there is no output schema and no annotations. The description implies an element ID is returned, but it does not explicitly state the return format, possible null/error conditions, or selection behavior among multiple suitable parents. This leaves some ambiguity for an agent relying solely on the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully documents page_id as a WordPress page ID. The description adds useful context by specifying that the page should be an Elementor page, which narrows the parameter's meaning and helps the agent select appropriate inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Find') with a clear resource ('suitable parent column or container element ID') and context ('for inserting widgets on an Elementor page'). It is distinguishable from sibling tools like wp_elementor_find_widgets or wp_elementor_get_structure, so an agent can understand what this tool uniquely does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: it should be used when preparing to insert widgets into an Elementor page and a parent element ID is needed. It does not explicitly name alternatives or exclusions, but the intended usage is apparent from the phrasing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find widgets on a page filtered by widget_type (e.g. button, image, raven-heading)
| Name | Required | Description | Default |
|---|---|---|---|
| page_id | Yes | ||
| widget_type | Yes | Widget type to filter by |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It indicates a read operation (find) and filtering, but it does not specify the output format, whether it returns widget IDs or full details, or any side effects. The absence of explicit read-only or non-destructive mention is a gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no waste. It is front-loaded with purpose and filter criteria. However, it could still be considered slightly under-specified given the lack of other elements.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and annotations, the description should explain what the tool returns. It covers the input and filter but omits output details, leaving the agent uncertain about the return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only widget_type has a description). The description adds example values for widget_type, which is helpful, but does not elaborate on page_id or provide additional format constraints beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds widgets on a page and filters by widget_type. It gives specific examples (button, image, raven-heading), distinguishing it from sibling tools like wp_elementor_get_widget_catalog or wp_elementor_list_elements.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for finding specific widgets on a page but does not provide explicit guidance on when to use this tool versus alternatives such as listing all widgets or searching content. No exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full Elementor page structure including element tree JSON. Page must be built with Elementor.
| Name | Required | Description | Default |
|---|---|---|---|
| page_id | Yes | WordPress page ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It implies a read-only operation but does not disclose error handling, permissions, or what happens if the page doesn't exist or isn't built with Elementor.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first conveys the core purpose, the second adds a key prerequisite. It is front-loaded and concise with no extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one parameter and no output schema, the description adequately covers the purpose and a key constraint. However, lacks details on return structure behavior, but this is partially mitigated by the clear purpose statement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of the single parameter (page_id) with a description 'WordPress page ID'. The description adds the constraint that the page must be built with Elementor, but does not add further semantic information about the parameter itself.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get'), the resource ('full Elementor page structure'), and the output format ('including element tree JSON'). It distinguishes from sibling tools like wp_elementor_find_widgets by focusing on the entire page structure.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear prerequisite ('Page must be built with Elementor'), which guides when to use this tool. While it doesn't explicitly list alternatives, the context of sibling tools implies it's for reading the structure, not for modifications.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the display conditions for an Elementor Theme Builder template — which pages or post types it shows on.
| Name | Required | Description | Default |
|---|---|---|---|
| template_id | Yes | Template ID from wp_elementor_list_theme_templates |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of disclosing behavior. The verb 'Get' implies a read-only operation, and the description clarifies what information is returned conceptually. However, it does not disclose output format, error behavior, or whether any side effects occur, which keeps it at an adequate rather than rich level.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused sentence with no filler. It front-loads the action and resource, then adds a helpful clarifying clause, earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple one-parameter getter with no output schema, and the description gives enough context for an agent to understand what it retrieves and why. It could elaborate on the exact shape of the returned conditions, but that is not necessary for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single parameter already described as 'Template ID from wp_elementor_list_theme_templates'. The description does not add parameter-specific details, but with full schema coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and names a precise resource ('display conditions for an Elementor Theme Builder template'). The clarifying clause 'which pages or post types it shows on' makes the tool's purpose easy to distinguish from the sibling wp_elementor_set_template_conditions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes it clear that this is a retrieval tool, and the sibling name wp_elementor_set_template_conditions provides an implicit contrast for when to use one versus the other. There is no explicit 'use this instead of...' routing or exclusion, but the context is clear enough for correct selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the Elementor widget catalog with editable settings per widget type.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only implies a read operation but does not explicitly state side effects, authentication requirements, or what the output contains beyond 'catalog with editable settings'. This is minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the verb and resource, and contains no extraneous information. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (no params, no output schema, no annotations), the description is adequate but lacks detail on the format of the catalog and what 'editable settings' entails. It does not fully prepare the agent for interpreting the return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is 100% (trivially). Per the guidelines, 0 parameters warrants a baseline of 4. The description adds no parameter info because there are none, so it meets the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the Elementor widget catalog with editable settings per widget type. It uses a specific verb and resource, and the purpose is distinguishable from siblings like wp_elementor_find_widgets or wp_elementor_list_elements.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as wp_elementor_find_widgets or wp_elementor_list_elements. There is no mention of prerequisites, context, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Insert a section scaffold (section+column or container) with widgets. Use preset hero/cta/features or custom children. confirm:true required in safe mode.
| Name | Required | Description | Default |
|---|---|---|---|
| preset | No | Built-in section preset | |
| confirm | No | ||
| page_id | Yes | ||
| children | No | Custom widget list (overrides preset) | |
| position | No | end |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only mentions safe mode requirement. It fails to mention required permissions, effect on existing content, error conditions, or whether the operation is reversible. The description is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences. The first sentence front-loads the primary purpose, and the second sentence adds a critical usage note. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters including a nested array, no output schema, and no annotations, the description is too brief. It does not explain what a 'section scaffold' entails, how presets work (what widgets they include), the structure of custom children, or any side effects. The tool is incomplete for an AI agent to use correctly without additional knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 40%, meaning most parameters lack descriptions. The description repeats only what is already in the schema (presets and custom children). It does not clarify page_id's usage, position's default, or confirm's specifics (beyond safe mode). The description adds minimal value to parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool inserts a section scaffold with widgets, and specifies presets vs custom children. This distinguishes it from siblings like wp_elementor_insert_widget and wp_elementor_update_element, which modify existing elements rather than creating a new section structure.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides one usage guideline: 'confirm:true required in safe mode'. However, it does not explicitly state when to use this tool over alternatives (e.g., when to use a preset vs custom children, or when to use wp_elementor_insert_widget instead). More guidance on context would improve.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Insert a widget into a column or container. Requires parent_id from wp_elementor_list_elements. Use confirm:true when safe mode is on.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No | Required when safe mode is enabled | |
| page_id | Yes | ||
| settings | No | ||
| parent_id | Yes | Parent column or container element ID | |
| widget_type | Yes | Widget type from catalog |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden. It correctly implies a write operation ('Insert'), but does not disclose potential side effects, reversal capabilities, or success/failure details. The mention of safe mode and confirm adds some transparency, but overall behavioral context is limited.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with only two sentences, no redundancy, and no fluff. Every sentence adds value: the first states the core purpose, the second covers usage conditions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters (including a nested object), no output schema, and no annotations, the description is minimal. It covers the essential prerequisite and safe-mode requirement, but lacks information on the settings object, expected response, or error handling, making it moderately complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides descriptions for 3 of 5 parameters (60% coverage), and the tool description does not add any additional meaning beyond what is in the schema. For example, 'settings' and 'page_id' are not explained further. Baseline 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Insert a widget'), the target resource ('into a column or container'), and specifies a prerequisite requirement ('Requires parent_id from wp_elementor_list_elements'), effectively distinguishing it from sibling tools like wp_elementor_clone_element or wp_elementor_update_element.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance, noting the need for a parent_id obtained from wp_elementor_list_elements and the confirm parameter when safe mode is on. It does not directly state when not to use this tool or list alternatives, but the context is clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all Elementor elements on a page as a flat index with id, widgetType, text preview, and is_editable flag
| Name | Required | Description | Default |
|---|---|---|---|
| page_id | Yes | WordPress page ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must bear the full burden. It discloses the return format as a flat index with specific fields, implying a read-only operation. However, it omits details like error handling (e.g., missing page), performance characteristics, or whether the list is exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately states the action (list), scope (all Elementor elements on a page), and key output fields. No unnecessary words—perfectly front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple parameter set and lack of output schema, the description covers the core functionality. However, it misses context about empty results, invalid page_id, or data format (e.g., id type). Slightly more completeness would help, but it's adequate for a straightforward tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter page_id, described as 'WordPress page ID'. The tool description adds 'on a page' but does not enhance the schema's meaning. Baseline of 3 is appropriate as no extra clarification is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all Elementor elements on a page as a flat index, specifying the output fields (id, widgetType, text preview, is_editable flag). This distinguishes it from related siblings like wp_elementor_get_structure or wp_elementor_find_widgets, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. For instance, it does not compare with wp_elementor_get_structure or mention prerequisites like page_id validity. A user would benefit from explicit context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all items in an Elementor repeater widget (carousel slides, testimonials, photo roller images). Works on page IDs and Theme Builder template IDs.
| Name | Required | Description | Default |
|---|---|---|---|
| page_id | Yes | Page or template ID | |
| element_id | Yes | Element ID from wp_elementor_list_elements |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. The verb 'List' and the phrase 'all items' imply a non-mutating read operation with no filtering, which is useful. However, it does not disclose what the returned items look like, whether item IDs are included for use with update/remove repeater tools, or how invalid element IDs are handled.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused sentence that leads with the core action, then adds concrete examples and supported ID contexts. Every part earns its place; there is no filler or redundant elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read-only list tool with fully described schema properties, the description is nearly complete. It names the exact resource, gives real-world widget examples, and states valid ID sources. The main gap is the absence of an output schema or any statement about the return structure, but this is minor given the low complexity of the operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both page_id and element_id already have clear descriptions. The tool description adds no new parameter-level meaning beyond what the schema provides; it mostly restates that page IDs and template IDs are supported, which is already present in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: 'List all items in an Elementor repeater widget.' It additionally gives concrete widget examples (carousel slides, testimonials, photo roller images) and clarifies that both page IDs and Theme Builder template IDs are supported, which clearly distinguishes it from sibling tools like wp_elementor_list_elements.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly establishes the intended use case: retrieving all items inside a repeater widget, and it explicitly states valid input ID types (page IDs and Theme Builder template IDs). It does not explicitly compare against alternatives or state exclusions, but the resource scope is specific enough that an agent can infer when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all Elementor Theme Builder templates (headers, footers, singles, archives). Returns template IDs usable with other elementor tools.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Filter by template type |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. 'List' clearly signals a read-only operation, and the description adds that it returns template IDs. However, it does not disclose whether results are paginated, whether all templates are returned in one response, or what additional metadata may be included.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no filler. The purpose is front-loaded, the template categories are named, and the downstream value of the returned IDs is stated efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with one optional parameter and no output schema, the description is largely complete: it names the resource, the categories, and the returned value. The only notable gap is the absence of any mention of pagination or response shape beyond 'template IDs,' but this is a minor issue at this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage: the single optional 'type' parameter has an enum and its own description. The tool description does not add any additional meaning beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List'), a specific resource ('Elementor Theme Builder templates'), and enumerates the template categories. It also explains the key output ('template IDs usable with other elementor tools'), which distinguishes it from generic list tools and other Elementor structure tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the usage context clear: use it when you need an inventory of Theme Builder templates or their IDs for downstream Elementor operations. It does not explicitly name alternatives or say when not to use the tool, but the scoped resource and the 'usable with other elementor tools' note provide solid situational guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Publish a draft Elementor Theme Builder template so it goes live. Requires confirm: true when safe mode is on.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No | Set true to confirm publish when safe mode is enabled | |
| template_id | Yes | Template ID from wp_elementor_list_theme_templates |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of explaining behavior. It does disclose that the template transitions from draft to live and that safe mode requires confirmation. However, it does not mention whether republishing an already-live template is safe, whether the action is reversible, or what the tool returns. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler. The core action is front-loaded, and the critical safe-mode condition is placed in the second sentence. Every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter action with full schema coverage, the description is largely complete. It explains the purpose, the transition to live, and the confirmation requirement. Minor gaps, such as defining how safe mode is determined or describing the response, are not critical for successful invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters well, including that template_id comes from wp_elementor_list_theme_templates and that confirm is tied to safe mode. The description adds marginal value by emphasizing the confirm requirement, but most parameter meaning is already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Publish'), a precise resource ('draft Elementor Theme Builder template'), and the intended outcome ('goes live'). This is clearly distinguished from the many read/list and template-condition sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool: publishing a draft Elementor Theme Builder template. It also includes the key conditional requirement about confirm in safe mode. It does not explicitly name alternatives or exclusions, but there is no obvious sibling that competes for this exact action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Regenerate Elementor CSS assets for a page after structural changes
| Name | Required | Description | Default |
|---|---|---|---|
| page_id | Yes | WordPress page ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not state whether existing CSS is overwritten, whether the operation is safe to rerun, what side effects occur, or what success/failure looks like.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler. The action, target, and trigger are all stated efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, no-output-schema tool, the description is reasonably complete: it names the action, the affected resource, and the appropriate timing. It could add a note about safety or side effects, but it does not leave an agent guessing about what resource to pass or when to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and page_id is already described as 'WordPress page ID'. The description adds only a generic 'for a page' context, not new type, format, or constraints, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Regenerate') and identifies a precise resource ('Elementor CSS assets for a page'), plus the trigger context ('after structural changes'). No sibling tool covers CSS regeneration, so it is clearly distinguishable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear usage context by specifying when to call it ('after structural changes'), which helps an agent decide. It does not explicitly name alternatives or exclusions, but the sibling list does not contain an obvious competing CSS-regeneration tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a widget, section, or container by element ID. confirm:true required when safe mode is on.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No | ||
| page_id | Yes | ||
| element_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses a behavioral aspect (confirm requirement in safe mode), but lacks details on permanence, permissions, or side effects of removal. No annotations are provided, so the description carries the full burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise with only two short sentences, front-loading the key action and resource. No wasted words, but could be slightly more structured for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given it is a destructive tool with three parameters and no output schema or annotations, the description lacks context on prerequisites, return values, error conditions, and the role of 'page_id'. The agent may struggle to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the role of 'element_id' and the 'confirm' parameter, but does not address 'page_id' at all. Since schema coverage is 0%, this leaves one parameter completely undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Remove') and specifies the target resource ('a widget, section, or container by element ID'), distinguishing it from sibling tools like insert or clone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The description only mentions a condition ('confirm:true required when safe mode is on') but does not differentiate from other Elementor manipulation tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove an item from an Elementor repeater widget by zero-based index. Requires confirm: true when safe mode is on.
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | Zero-based item index from wp_elementor_list_repeater_items | |
| confirm | No | Set true to confirm when safe mode is enabled | |
| page_id | Yes | Page or template ID | |
| element_id | Yes | Element ID from wp_elementor_list_elements |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does disclose the confirmation requirement when safe mode is on, which is useful, but it does not state whether the removal is permanent or how remaining item indices are affected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two tight sentences with no filler. The core action and target come first, and the safe-mode requirement is stated succinctly without restating schema fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for basic invocation, covering the operation, the indexing semantics, and the confirmation condition. However, it does not mention return values, irreversibility, or reindexing behavior, and no annotations compensate for these omissions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by clarifying that the index is zero-based and explaining the confirm parameter's role in safe mode, going beyond the schema's basic field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the exact action (remove), the resource (Elementor repeater widget), and the indexing scheme (zero-based index). This clearly communicates the tool's function and distinguishes it from the sibling add/update repeater tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool should be used when removing an item from a repeater, and the schema's index parameter references wp_elementor_list_repeater_items. However, there is no explicit when-to-use or when-not-to-use guidance, nor any direct comparison with the add/update repeater sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-save Elementor JSON on a page to fix corruption (e.g. $400n heading text). Use after duplicate issues or broken templates.
| Name | Required | Description | Default |
|---|---|---|---|
| page_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden of disclosing behavior. It does reveal that the tool re-saves and modifies Elementor JSON, but it does not mention side effects such as whether existing layout changes are overwritten, whether a backup or revision is recommended, whether permissions are needed, or whether the operation is reversible. For a mutating repair operation, this is a meaningful gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loads the core action, and includes a concrete example. Every sentence earns its place with no redundant or vague filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one required parameter, no nested objects, no output schema), and the description provides a clear purpose and trigger. However, it lacks important operational context such as side effects, the exact meaning of page_id, and what to expect after execution, making it adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only 'page_id' as an integer with no description, and schema description coverage is 0%. The description mentions 'a page' but never explains that page_id is the WordPress page/post ID or how to obtain it. The description does not meaningfully compensate for the missing parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Re-save Elementor JSON on a page') and an explicit purpose ('fix corruption'), with a concrete symptom example ('$400n heading text'). It is understandable and distinct from the related page/Elemenator tools, though it does not explicitly differentiate itself from siblings like wp_elementor_regenerate_css.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: 'Use after duplicate issues or broken templates.' It gives situational triggers but stops short of stating when not to use it or naming alternative tools, so it has no exclusions but is still useful guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace all display conditions on an Elementor Theme Builder template. Use 'include/general' to show on all pages, 'include/singular/page/43' for a specific page.
| Name | Required | Description | Default |
|---|---|---|---|
| conditions | Yes | Condition strings e.g. ['include/general'] or ['include/singular/page/43'] | |
| template_id | Yes | Template ID from wp_elementor_list_theme_templates |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it does disclose the most critical trait: 'Replace ALL display conditions' warns that existing conditions are overwritten, not appended. However, it does not disclose side effects (e.g., CSS regeneration, impact on published templates), whether the operation is reversible, or what happens if invalid condition strings are passed. Partial but honest disclosure of a mutating operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero filler. The core action is front-loaded in sentence one, and the examples in sentence two earn their place by teaching the condition format. No information is repeated from the schema, and no word is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema and no annotations, the description should compensate by indicating what the caller can expect in return and how invalid conditions are handled; neither is addressed. The two examples cover the most common cases, so the tool is callable for typical scenarios, but the missing response/error semantics leave an agent guessing about failure modes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so the baseline is 3, but the description adds real semantic value by decoding the otherwise-opaque condition strings: 'include/general' means show on all pages and 'include/singular/page/43' targets one specific page. This domain knowledge is exactly what the raw schema examples fail to convey. It does not cover the full condition syntax space, but the added interpretation justifies a point above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise action ('Replace all display conditions') on a specific resource ('an Elementor Theme Builder template'). The qualifier 'all' signals the wholesale-replacement semantic, distinguishing it from additive or partial updates, and the sibling getter (wp_elementor_get_template_conditions) is clearly contrasted by the set/replace verb. No ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The examples ('include/general' for all pages, 'include/singular/page/43' for a specific page) provide useful context for common intents, but the description never explicitly says when to prefer this tool over alternatives or mentions the read-before-replace flow with the sibling getter. Usage guidance is implied through examples rather than stated as selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find a button (or raven-button) by matching button text and update text and/or URL.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | New button URL | |
| page_id | Yes | ||
| new_text | No | New button label | |
| match_text | Yes | Existing button text to find |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It mentions update (mutation) but lacks details on required permissions, what happens if multiple buttons match, or whether the tool only works with Elementor/raven-button widgets. Significant gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with action and target, no wasted words. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, no annotations. The description does not explain what the tool returns (e.g., success/failure, updated element ID), or behavior on no match or multiple matches. For a tool with 4 parameters and a mutation action, this is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75% (3 of 4 params have descriptions). The description adds that match_text is for finding the button, and new_text/url are updates. It does not describe page_id (missing from description). Baseline 3 is appropriate since schema already covers most params sufficiently.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Find and update') and resource ('button or raven-button'), with clear criteria (matching button text) and actions (update text/URL). It distinguishes from sibling tools like wp_elementor_update_text which don't target buttons specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need to update a button's text or URL based on its current text, but provides no explicit guidance on when to use vs. alternatives like wp_elementor_update_text or wp_elementor_update_element. Context is clear but no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an Elementor widget by element ID. Supports all catalog-editable widgets (heading, text-editor, button, image, icon-box, icon-list, raven-*).
| Name | Required | Description | Default |
|---|---|---|---|
| page_id | Yes | ||
| settings | Yes | Widget settings to merge — use wp_elementor_get_widget_catalog for allowed keys | |
| element_id | Yes | Elementor element ID from wp_elementor_list_elements |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description only hints at limitations (supports catalog widgets) but omits critical traits like whether settings merge or replace, side effects, or error handling for invalid element IDs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two short sentences—and front-loads the core action with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite good schema coverage, the description lacks vital context for an update tool: no explanation of merge vs. replace behavior, return values, or error states. This omission could lead to misuse.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes element_id and settings well; the tool description adds no parameter-specific details beyond listing supported widget types. For page_id, no additional guidance is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an Elementor widget by element ID', specifying the verb (update) and resource (widget). It also lists supported widget types, distinguishing it from specialized siblings like wp_elementor_update_button.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for any catalog-editable widget but does not explicitly guide when to use this general tool versus specialized ones (e.g., wp_elementor_update_button) or mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an image widget by element_id or match_url. Set image_id, image_url, and/or caption.
| Name | Required | Description | Default |
|---|---|---|---|
| caption | No | ||
| page_id | Yes | ||
| image_id | No | WordPress attachment ID | |
| image_url | No | Image URL | |
| match_url | No | Find image by current URL substring | |
| element_id | No | Target element ID (preferred) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It fails to mention side effects (e.g., overwriting existing image), permission requirements, reversibility, or whether partial updates are allowed. For a mutation tool, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with action and key methods. Every word is necessary; no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks information about return values, required parameters (page_id is only in schema), and prerequisites. For a mutation tool without output schema, this is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%, and the description adds minimal value beyond the schema: it rephrases existing descriptions but does not clarify usage nuances (e.g., whether partial updates are supported or how image_url relates to image_id). It meets baseline expectations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('update'), resource ('image widget'), and specifics (by element_id or match_url, setting image_id, image_url, caption). It distinguishes well from sibling tools that update other widget types (e.g., text, button).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides two identification methods (element_id preferred, match_url as alternative) and lists settable fields. However, it does not explicitly state when to use this tool versus other update tools, nor does it mention prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Partially update an item in an Elementor repeater widget by zero-based index. Only provided fields are changed; others are preserved.
| Name | Required | Description | Default |
|---|---|---|---|
| item | Yes | Fields to update e.g. {caption: 'New caption'} | |
| index | Yes | Zero-based item index from wp_elementor_list_repeater_items | |
| page_id | Yes | Page or template ID | |
| element_id | Yes | Element ID from wp_elementor_list_elements |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It does disclose the key partial-update behavior: only provided fields are changed and others are preserved. However, it does not mention error behavior for invalid indexes or missing elements, whether the operation is reversible, any permission requirements, or what the tool returns, leaving notable uncertainty for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action and scoping ('Partially update an item in an Elementor repeater widget by zero-based index'), and every sentence earns its place. The second sentence clarifies the preservation guarantee without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core operation and partial-update semantics, and the schema handles parameter documentation. However, because there is no output schema and no annotations, the description does not fully cover edge cases like invalid indices, nonexistent repeater items, or the return value. It also lacks explicit routing among the closely related repeater sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all four parameters, including the zero-based index and the 'Fields to update' nature of the item object, so schema coverage is 100%. The description adds the useful semantic of partial update and preservation, but it does not provide per-parameter details beyond what the schema already states, keeping this at the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('partially update'), a specific resource ('item in an Elementor repeater widget'), and the addressing mechanism ('zero-based index'). It clearly distinguishes this from sibling add/remove/list repeater tools by emphasizing that it modifies an existing item rather than adding or removing one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the intended use case—updating only some fields of an existing repeater item while preserving the rest—but it never explicitly says when to prefer this over wp_elementor_add_repeater_item or wp_elementor_remove_repeater_item. It also does not state the prerequisite that the item must already exist or that the index should come from wp_elementor_list_repeater_items, though that hint appears in the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find a heading or text-editor widget by matching existing text and replace it. Creates a snapshot before updating.
| Name | Required | Description | Default |
|---|---|---|---|
| page_id | Yes | ||
| new_text | Yes | Replacement text | |
| match_text | Yes | Existing text to find (partial match supported) | |
| widget_type | No | Widget type: heading, text-editor, or raven-heading | heading |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description discloses snapshot creation before update, which is a behavioral trait. However, it does not discuss permissions, error handling, or destructive potential beyond basic replacement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the action. No unnecessary words; every sentence provides essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description covers core action and snapshot creation but omits return value, error behavior (e.g., widget not found), and required permissions. For a mutation with no output schema, more detail on outcomes would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only widget_type and match_text have descriptions). Description mentions 'match existing text' but doesn't add meaning for page_id or new_text beyond what schema provides. No parameter format or constraints are clarified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it finds and replaces text in heading or text-editor widgets. This specific verb-resource combination distinguishes it from siblings like wp_elementor_insert_widget or wp_elementor_update_button.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for updating widget text, but no explicit when-to-use or when-not-to-use guidance is provided. No mention of prerequisites or comparison to sibling tools (e.g., wp_elementor_update_element).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export site structure as JSON tree (pages, posts, menus, taxonomies, redirects)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description fails to disclose behavioral traits such as being read-only, performance implications, or required permissions. The tool is likely a read operation, but this is not stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, concise sentence that clearly communicates the tool's purpose with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no parameters and no output schema, the description adequately explains what is exported. However, it could mention that it is a read operation and the output format more explicitly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is 100%. The description adds no parameter information, but with no parameters, a baseline of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool exports site structure as JSON tree covering pages, posts, menus, taxonomies, and redirects. It distinguishes itself from siblings which focus on individual CRUD operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus alternatives. Many sibling tools perform individual content operations, but no explicit context is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a sitemap of published pages and posts
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits, but it only states the purpose. It does not mention whether the sitemap is public, overwritten, or requires authentication, nor does it describe side effects or return behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that gets straight to the point with no filler. It is appropriately front-loaded, though it could benefit from slight expansion without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description should hint at the return value (e.g., the sitemap content in the chosen format). It does not, leaving the agent to guess the output structure. For a simple tool, completeness is low.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, and the description does not mention the 'format' parameter or explain its values (json/xml). The agent receives no additional meaning beyond the enum names, which is insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Generate' and the resource 'sitemap of published pages and posts', specifying exactly what it produces. Among sibling tools, no other creates a sitemap, distinguishing it effectively.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor are there any exclusions or recommendations. The tool is unique among siblings, but the description lacks contextual usage advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get ACF field values and catalog for a post/page (requires ACF plugin)
| Name | Required | Description | Default |
|---|---|---|---|
| post_id | Yes | WordPress post or page ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. 'Get' communicates a read-only operation, 'values and catalog' indicates the shape of the response, and 'requires ACF plugin' surfaces the key dependency. It does not cover error behavior if the plugin is missing, but for a simple read the essentials are present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded verb and resource, with the prerequisite tucked into a parenthetical. Every word earns its place and there is no redundant restatement of the input schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read tool, the description covers the input, the plugin dependency, and the high-level return contents. It could add detail about the exact catalog/response format, but no output schema exists and the description is adequate for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single post_id parameter is fully documented in the schema with 'WordPress post or page ID', so schema coverage is 100%. The description adds only a brief confirmation that the tool applies to posts/pages, not meaningful new semantic detail, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Get' with a clear resource: ACF field values and catalog for a post/page. It also notes the ACF plugin prerequisite, which distinguishes it from generic metadata or page getters like wp_get_meta_catalog and wp_get_page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context 'for a post/page' and the plugin prerequisite imply when the tool applies, and 'requires ACF plugin' is a useful condition. However, no alternative tools are named and there is no explicit when-not-to-use guidance compared with sibling read tools like wp_get_meta_catalog.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get MCP activity log with optional filters
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| action | No | ||
| per_page | No | ||
| object_type | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any behavioral traits. It does not state whether the tool is read-only, destructive, requires authentication, or what the response format is. The description adds no behavioral context beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, making it concise. However, it omits important details that should be present, such as parameter explanations or usage context. It is under-specified rather than efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, no annotations, and four parameters with no descriptions, the description is severely incomplete. An agent cannot determine the return format, behavior, or proper parameter usage. The tool's complexity is low, but the description fails to provide essential context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has four parameters (page, per_page, action, object_type) with zero schema descriptions (0% coverage). The description only mentions 'optional filters' but does not explain what each filter does or its format. This minimal addition does not compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: 'Get MCP activity log with optional filters'. The verb 'Get' and resource 'MCP activity log' are specific. However, it does not differentiate from other get/list tools like wp_get_settings or wp_get_site_info, which are separate resources. Still, the purpose is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Among many sibling tools like wp_list_posts or wp_health_check, there is no mention of use cases or contexts where this log retrieval is appropriate. The description is purely functional.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a WooCommerce Booking by ID (requires WooCommerce Bookings plugin)
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Booking ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It conveys that this is a read/get operation and that the Bookings plugin is required, which is useful. However, it does not disclose failure behavior, return shape, or what happens if the ID is invalid or the plugin is inactive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One compact sentence with the action front-loaded and the plugin requirement in a short parenthetical. There is no redundant or filler content; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-ID getter with one required parameter and no output schema, the description provides the essential invocation facts: resource, ID, and plugin prerequisite. It does not describe error/return behavior, but the tool's simplicity and obvious return value make it sufficiently complete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully documents the single id parameter with type and description, so schema coverage is 100%. The description's phrase 'by ID' reinforces but does not add new meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb ('Get') and a specific resource ('a WooCommerce Booking by ID'), clearly identifying what the tool does and the required plugin. It is distinct from sibling get tools like wp_get_order or wp_get_product because it explicitly names WooCommerce Booking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states the key precondition: the WooCommerce Bookings plugin must be installed. It provides enough context for an agent to know when this tool is appropriate, and there is no competing booking-fetch sibling that would cause confusion. It stops short of explicitly naming alternatives or when-not conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single custom post type item by ID
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| post_type | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the disclosure burden. It clearly signals a read-only retrieval operation via 'Get,' but it does not describe return format, error behavior, or whether unsupported/draft items are included. The basic read behavior is transparent, but edge-case behavior is left unstated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It names the action, the resource, the retrieval key, and the singularity of the result in eight words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter getter, the description is almost sufficient, but there is no output schema and no annotation support. It does not state what an 'item' contains, how post_type interacts with the lookup, or what happens when the ID is not found, leaving some reasonable gaps for an agent invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must add meaning to the parameters. It does: 'custom post type' gives semantic context to post_type and 'by ID' explains the id parameter. Both required parameters are inferable from the description, though no explicit parameter-by-parameter mapping is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('custom post type item') with a clear selection criterion ('by ID'). It clearly distinguishes this from list/create/update/delete sibling tools in the same CPT family.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrasing implies the tool should be used when a single CPT item and its ID are already known, which is useful context. However, it does not explicitly compare against alternatives like wp_list_cpt_items or wp_get_post, or state when one should choose this over another.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a custom MCP webhook by ID
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Webhook ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. 'Get' implies a read-only operation, but the description does not state behavior for missing or invalid IDs, whether the full webhook configuration is returned, or any required permissions. The absence of an output schema makes these gaps more significant.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler or redundancy. It front-loads the action, resource, and the identifying parameter, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple one-parameter getter, so the description is minimally viable, but it is thin given the absence of annotations and output schema. It does not describe what the returned webhook object looks like, how to discover IDs, or how this webhook type relates to sibling form/WooCommerce webhook tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents the only parameter, id, as 'Webhook ID' with 100% coverage. The description adds no new parameter meaning beyond restating the by-ID relationship, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Get a custom MCP webhook by ID.' It clearly indicates a singleton read operation and distinguishes it from sibling tools that create, update, delete, list, or test webhooks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'by ID' implies this tool should be used when a specific webhook ID is already known, but it does not explicitly state when to prefer this over wp_list_custom_webhooks or other webhook tools. Alternatives are not named or excluded.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get Ninja Form details including fields and notification actions
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Form ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral transparency burden. The word 'Get' implies a read operation, and the phrase 'including fields and notification actions' usefully previews the output, but the description does not explicitly state side effects, permission requirements, or behavior for invalid/nonexistent IDs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one sentence, front-loaded with the verb and resource, and contains no filler. The 'including fields and notification actions' clause adds meaningful detail without unnecessary length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read operation with no output schema, the description provides enough information about what is returned. It could also note that this retrieves a single form and point to wp_list_forms for listing, but that is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'id' is already fully described in the input schema as 'Form ID', so the description adds little beyond the schema. However, it does provide useful context by identifying the resource type as a Ninja Form.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and a clearly identified resource ('Ninja Form details'), and further specifies the key content areas: fields and notification actions. This distinguishes it from list-oriented siblings like wp_list_forms and notification-updating tools like wp_update_form_notifications.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for retrieving details about a single Ninja Form, but it does not explicitly state when to use it versus alternatives. It does not mention that wp_list_forms is for listing forms or that wp_update_form_notifications is for modifying notification actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single media item with metadata
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral disclosure. It only states the basic function without mentioning safety (e.g., read-only), side effects, authorization requirements, or rate limits. The agent learns nothing beyond the operation's purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It is front-loaded with the core action. However, it could include more detail (e.g., what metadata includes) without becoming overly verbose, which prevents a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single required parameter, no output schema), the description covers the basic purpose. However, it lacks information about the return structure, error conditions, and the scope of 'metadata'. It is minimally adequate but has gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since schema description coverage is 0%, the description should elaborate on the 'id' parameter but does not. It only implies 'id' identifies the media item, which is already obvious from the tool name and purpose. No additional meaning is added beyond the schema's type and required flag.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a single media item with metadata, using the verb 'Get' and specifying the resource 'media item'. It distinguishes from sibling tools like wp_list_media (list) and wp_delete_media (delete).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like wp_list_media or wp_get_post. No context on prerequisites or scenarios is given. Usage is only implied by the required 'id' parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get unified meta field catalog across ACF, AIOSEO, and other registered adapters
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. 'Get' signals read-only intent and 'unified across adapters' signals aggregation, but the return structure, adapter discovery behavior, and error semantics are not described. Acceptable but minimal for a zero-parameter read-only tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler. Every word adds meaningful scope or purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter read-only catalog tool, the description is nearly complete: an agent knows exactly what action to invoke and what resource to expect. The main gap is that the exact contents of the catalog are unspecified and there is no output schema to fill that void, but this is a minor issue given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero properties and 100% schema description coverage, so the baseline is 4. There are no parameters to document, and the description does not need to compensate for any missing parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Get'), a specific resource ('unified meta field catalog'), and scopes it across ACF, AIOSEO, and other registered adapters. This clearly distinguishes it from narrower siblings like wp_get_acf_fields or wp_get_page_seo.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: when a cross-adapter meta field catalog is needed. However, it never explicitly states when not to use it or names alternatives, leaving the routing decision to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full WooCommerce order details including line items and addresses
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Order ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden. 'Get' clearly implies a non-mutating read operation, and the mention of line items and addresses gives some return-content context. However, it does not describe error behavior, permissions, or the full response shape, which would be more important if an output schema were absent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or redundant details. Every word earns its place by conveying the resource, scope, and key contents.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter with one well-documented parameter and no output schema, the description covers the key returned content (line items and addresses). It could mention additional order fields or error conditions, but the current description is sufficient for an agent to correctly invoke the tool in most cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage with a clear 'Order ID' description for the single 'id' parameter. The description adds no additional parameter semantics, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb ('Get'), a clear resource ('full WooCommerce order details'), and explicitly names content ('line items and addresses'). It clearly distinguishes this single-order retrieval tool from siblings like wp_list_orders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the retrieval context clear: use this when you need complete details for a specific order, including line items and addresses. It does not explicitly contrast with wp_list_orders or wp_update_order, but the intended use is evident from the wording.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full WordPress page data including raw and rendered HTML content
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Page ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description partially compensates by mentioning that the tool returns both raw and rendered HTML, which hints at the nature of the data. However, it does not disclose whether the tool requires authentication, whether it might be slow (e.g., due to rendering), or if it has any side effects (e.g., triggering hooks).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately conveys the tool's purpose and output. It contains no redundant words and is front-loaded with the key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read operation, the description is largely complete, specifying the returned content type. It could be improved by noting that the ID must correspond to an existing page, but overall it covers the essential context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage with a description for the 'id' parameter ('Page ID'). The description adds no further semantic detail, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action ('Get'), the resource ('full WordPress page data'), and the key output ('raw and rendered HTML content'). This distinguishes it from sibling tools like wp_get_post (for posts) and wp_list_pages (which lists pages but doesn't return full data).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives, such as wp_get_post for posts or wp_list_pages for a summary. No context is provided about prerequisites, limitations, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get SEO metadata for a page/post via All in One SEO (title, description, schema, etc.)
| Name | Required | Description | Default |
|---|---|---|---|
| page_id | Yes | WordPress page or post ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It accurately indicates a read operation ('Get') and names the data source ('All in One SEO'), but does not disclose behaviors such as what happens when the plugin is missing, error conditions, or the exact shape of the returned metadata beyond examples.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler. It front-loads the action and resource, then lists representative return fields. The 'etc.' is minor and does not detract from the overall efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter with one well-documented parameter and no output schema, the description provides enough context: what is fetched, the source, and example output fields. It could be more complete by noting plugin dependency or error handling, but those are not critical for basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with page_id described as 'WordPress page or post ID'. The description's mention of 'page/post' adds a small clarification that page_id may refer to either type, but it does not provide meaning beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get') and resource ('SEO metadata for a page/post via All in One SEO'), with concrete examples of what is included. This clearly distinguishes it from sibling tools like wp_get_page (general page data) and wp_update_page_seo (write operation).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: when you need SEO metadata for a single page or post. However, it does not explicitly mention alternatives or scenarios where wp_audit_seo or wp_get_page would be more appropriate, so usage guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Detect conflicting active plugins (SEO, cache, redirect groups)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It implies a read-only detection operation but does not state whether it modifies anything, what it returns, or what constitutes a conflict. The ambiguous term 'conflicting' is the only signal and it is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the action and resource. There is no filler, and every word contributes to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description should at least hint at what kind of result is returned (list, report, severity levels). It does not. The low parameter complexity partially mitigates this, but the missing return/usage context leaves an agent without enough information to reliably use the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. There are no parameter details to explain, and the description adds reasonable context about what the no-argument call scans.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Detect') and a specific resource ('conflicting active plugins'), with scoping categories (SEO, cache, redirect groups). It clearly distinguishes this from sibling tools like wp_list_plugins or wp_get_plugin_updates by focusing on conflicts rather than listing or update status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives such as wp_list_plugins, wp_health_check, or wp_audit_seo. It states only what it does, not the context or conditions under which it should be invoked.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List available plugin updates from WordPress.org
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. 'List' communicates a read-only operation and 'from WordPress.org' specifies the data source, but the description does not mention remote API calls, potential latency, caching, or what an update record contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler. 'List available plugin updates from WordPress.org' is compact, clear, and every word contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only operation, invocation is trivially complete: the description names the task and source. However, there is no output schema and the description does not hint at returned fields such as plugin name, current version, or available version, leaving a minor gap for agents that need to act on results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero properties, so there is nothing for the description to add about parameters. Baseline for a 0-parameter tool is 4, and the description appropriately omits parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States the exact action ('List') and resource ('available plugin updates') and adds the source 'from WordPress.org'. This clearly distinguishes it from sibling tools like wp_list_plugins (installed plugins) and plugin lifecycle tools like wp_activate_plugin.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use—checking for pending plugin updates—is strongly implied by 'available plugin updates', but the description gives no explicit when-to-use or when-not-to-use guidance and does not name alternatives. An agent must infer how it relates to wp_list_plugins and plugin management tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full WordPress post data including content, categories, and tags
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Post ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a read operation with no side effects, which is appropriate for a get tool. No annotations are present, so the description carries full burden; it does not mention auth needs or rate limits, but the simplicity limits risk.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that conveys the core purpose without unnecessary words. It could benefit from a bullet or structured format, but remains clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple single-parameter tool and no output schema, the description adequately covers what the tool does. It could mention return format, but is sufficient for a get operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'id' is described in the schema as 'Post ID', and the description adds no additional context. With 100% schema coverage, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function ('Get full WordPress post data') and specifies included data (content, categories, tags), distinguishing it from sibling tools like wp_get_page or wp_list_posts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., wp_get_page for pages, wp_list_posts for lists), nor any preconditions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full WooCommerce product details
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Product ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of conveying behavior. 'Get' clearly implies a read-only fetch with no mutation, which is good, but the description does not mention error behavior, required permissions, or what exactly 'full details' includes. This is acceptable for a simple getter but not richly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no filler or redundant phrasing. 'Full' adds useful scope clarification, and the structure is immediately parsable by an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter getter with no output schema, the description is reasonably complete: it names the action, resource, and scope. It could be slightly stronger by clarifying what set of fields are returned, but given the low complexity, it provides enough context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully documents the only parameter (id with description 'Product ID'), so schema description coverage is 100%. The description adds no parameter-level meaning beyond this, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Get') and a specific resource ('full WooCommerce product details'), making it clear this is a single-item retrieval tool. It distinguishes itself from siblings like wp_list_products, wp_create_product, wp_update_product, and wp_delete_product by signaling read-only retrieval of one product's complete data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives such as wp_list_products or wp_get_cpt_item. It does not mention prerequisites like knowing the product ID or when a product might be better fetched through another endpoint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get revision content by revision ID
| Name | Required | Description | Default |
|---|---|---|---|
| revision_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Get' implies a read operation, which is helpful, but the description does not disclose what exactly is returned (raw post content, metadata, or wrapped object), whether it can error on missing revisions, or that it is non-mutating. It adds no behavioral detail beyond what the tool's name already suggests.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler words; every word contributes to the core operation. It is not verbose, though its brevity reflects under-specification rather than efficient completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool, the core purpose is clear and the schema covers the required argument. However, with no output schema, no annotations, and no parameter descriptions, the agent is left guessing about the return shape, error behavior, and any caveats. It is minimally adequate for selecting the tool but not for fully understanding its contract.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema lists only revision_id with a type but no description, and schema_description_coverage is 0%. The phrase 'by revision ID' simply restates the parameter name and adds no meaning about valid formats, how to locate a revision ID, or how the ID maps to a specific revision. With no parameter descriptions, the tool description needed to compensate and did not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Get' with a clear resource ('revision content') and identifies the lookup key ('by revision ID'). Among siblings like wp_list_revisions, wp_get_revision_diff, and wp_restore_revision, 'content' distinguishes this as full-content retrieval rather than listing, diffing, or restoring. It does not explicitly contrast with those alternatives, but the combination of verb and resource is specific enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus wp_list_revisions or wp_get_revision_diff, nor any exclusions or prerequisites. An agent must infer that this is for fetching a single revision's content once an ID is known, but there is no context about how to obtain that ID or why this tool is preferable to the diff tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Diff a revision against the current post content (title, content, excerpt)
| Name | Required | Description | Default |
|---|---|---|---|
| revision_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully disclose behavior. It explains that a diff is computed against current content, which is helpful, but it does not state whether the operation is read-only, what the diff output looks like, how differences are represented, or whether any metadata is included in the result.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no filler. The verb and core comparison are front-loaded, and the field list adds useful scope without bloating the text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-oriented tool, the description covers the core purpose, but gaps remain: no output schema, no return format, no side-effect statement, and no guidance distinguishing it from sibling revision tools. It is adequate for basic invocation but not fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should compensate for the undocumented revision_id parameter. It only refers to 'a revision' generically and adds no practical meaning such as where to obtain revision_id, whether it comes from wp_list_revisions, or how it relates to a specific post.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific operation (diff), the resource (a revision), and the comparison target (current post content), and even lists the fields involved (title, content, excerpt). This clearly distinguishes it from siblings like wp_get_revision, wp_restore_revision, and wp_get_snapshot_diff.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not state when to use this tool versus alternatives such as wp_get_revision or wp_restore_revision. It implies a comparison use case but gives no exclusions, prerequisites, or routing guidance to help the agent pick between closely related revision tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read safe WordPress site settings
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates a read operation ('Read safe') but provides no additional detail on permissions, rate limits, or side effects. With no annotations, the description bears the full burden and falls short.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loading the purpose. It could be slightly more informative without adding length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema or annotations, the description should explain what 'site settings' includes and the return format. It does not, making it incomplete for a read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, so the description does not need to add parameter details. It is sufficient that it indicates the tool requires no input, though it could explicitly mention that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads WordPress site settings, with a specific verb and resource. However, it does not explicitly differentiate from sibling tools like wp_get_page or wp_update_settings, which would elevate clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as other getters or the update counterpart. The description lacks context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get site blueprint for agent discovery: theme, menus, adapters, Elementor/WooCommerce status, allowed post types
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. The verb 'Get' and the word 'blueprint' imply a read-only snapshot with no side effects, and the description lists the areas inspected. It does not discuss permissions, performance, or response size, but for a zero-parameter getter the primary behavior is reasonably clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single well-structured sentence that front-loads the purpose ('Get site blueprint for agent discovery') and then compactly lists the scope. Every word adds value and there is no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no output schema, the description gives a meaningful list of return areas: theme, menus, adapters, Elementor/WooCommerce status, and allowed post types. This is sufficient for an agent to decide to call it. It stops short of describing the exact response structure or explicitly contrasting it with similar overview tools, but the tool is simple enough that the description is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is no parameter semantics burden. The description appropriately focuses on what the blueprint contains rather than inventing parameter guidance. This matches the baseline for a no-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: 'Get site blueprint for agent discovery' and enumerates concrete contents: theme, menus, adapters, Elementor/WooCommerce status, allowed post types. This clearly differentiates it from the many sibling tools that operate on individual pieces of a site.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for agent discovery' gives a clear context for when this tool is useful: when an agent needs a broad site overview before acting. It does not explicitly name alternatives or exclusions, such as when to prefer wp_get_site_info or wp_site_audit, but the discovery-oriented framing provides sufficient practical guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get WordPress site information including theme, plugins, and permalink settings
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It implies a read-only operation but does not disclose caching, authentication needs, or output format. While it mentions three types of information, it lacks depth about what exactly is returned or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single efficient sentence that conveys purpose without redundancy. It could be slightly expanded to list all returned items, but it is well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite low complexity (0 params, no annotations, no output schema), the description only partially covers what the tool returns. It names three example items but does not indicate if there are more or the overall structure. This leaves some ambiguity for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so the baseline is 4. The description does not need to add parameter meaning beyond the schema, and it appropriately focuses on the output scope.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves WordPress site information, specifying theme, plugins, and permalink settings as examples. It uses a specific verb ('Get') and resource ('WordPress site information'), and it distinguishes itself from siblings like wp_list_themes and wp_get_settings by being a broader summary tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool or when to prefer alternatives. For instance, it doesn't mention that wp_list_themes or wp_get_settings provide more detailed, separate information. The description offers no context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Diff an MCP snapshot against the current post content
| Name | Required | Description | Default |
|---|---|---|---|
| snapshot_id | Yes | MCP snapshot ID from activity log |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. The verb 'Diff' implies a non-destructive read, but the description does not state what the output looks like (structured change list vs text diff), how errors are handled for invalid snapshot IDs, or whether it is safe to invoke freely.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single efficient sentence with the verb front-loaded and no filler. The word 'MCP' is slightly redundant given the tool context, but the sentence earns its place and is easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool this is minimally adequate, but gaps remain: there is no output schema and no annotations, so the agent cannot anticipate the diff format or result structure. The phrase 'post content' also raises a scope question — whether this works only for posts or for pages/CPTs — that is left unresolved.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — snapshot_id is fully documented in the schema as 'MCP snapshot ID from activity log', which is genuinely helpful. The tool description adds no parameter-level meaning beyond what the schema already provides, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Diff') and a specific resource pair (MCP snapshot vs current post content), making the core operation unambiguous. It distinguishes itself from the closest sibling wp_get_revision_diff by referencing 'snapshot' rather than 'revision', though it doesn't explicitly call out the difference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus its siblings. With wp_get_revision_diff, wp_get_activity_log, and wp_restore_snapshot all nearby, an agent gets no help choosing between comparing a snapshot and comparing a revision, or deciding when to diff versus restore.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a WordPress user by ID
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| include_email | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description's 'Get' conveys a read-only, non-destructive operation, which is the key behavioral trait. However, it does not disclose response shape, permissions, error behavior, or any additional side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler. Every word contributes to identifying the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter with one required parameter, the description is minimally viable: an agent can call it with the required id. But the lack of explanation for include_email and the absence of any output context leave notable gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it only explains that 'id' identifies the user. The 'include_email' boolean parameter is left completely unexplained, leaving the agent unsure what toggling it does.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get'), a resource ('WordPress user'), and the access method ('by ID'). This clearly distinguishes it from sibling tools like wp_list_users or wp_create_user.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'by ID' implies this tool should be used when retrieving a single known user, but it never explicitly names alternatives or says when not to use it. Guidance is present only by implication.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a WooCommerce native webhook by ID
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | WooCommerce webhook ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. 'Get' clearly indicates a read/retrieve operation with no mutation, which is the core behavioral trait. It does not discuss error cases, permissions, or response format, but for a simple get-by-ID operation this is a reasonable though not rich disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or repetition. Every word earns its place: action, resource type, and lookup key.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter getter, the description is largely complete: it names the resource and how to identify it. There is no output schema, so a phrase about the return value or error behavior could add completeness, but the tool's simplicity means the current description is unlikely to confuse an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents the only parameter, id, as a WooCommerce webhook ID with 100% coverage. The description's 'by ID' reinforces that but adds no new meaning beyond the schema, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Get'), a specific resource ('WooCommerce native webhook'), and the lookup key ('by ID'). It also distinguishes this tool from related siblings like wp_get_custom_webhook and wp_list_woocommerce_webhooks by using 'native' and 'by ID'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Using 'native' and 'by ID' implies this is the tool to call when you have a webhook ID and need a single WooCommerce webhook, not a custom webhook. However, it does not explicitly state when to prefer it over wp_list_woocommerce_webhooks or wp_get_custom_webhook, leaving some inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check WP MCP Control plugin health, REST availability, and security settings
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It describes what is checked (health, REST, security) but does not detail the internal behavior, output format, or potential side effects (e.g., network calls).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the key action. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Considering zero parameters, no output schema, and no annotations, the description covers the essence of the tool. However, it does not specify what the tool returns (e.g., a report or boolean), leaving a minor gap in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, making schema coverage 100%. The description adds no parameter information, but given no parameters, it is adequate. Baseline score 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Check WP MCP Control plugin health, REST availability, and security settings'. It uses specific verbs and resources, distinguishing it from sibling tools (which are mostly CRUD operations).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. It is implied as a diagnostic tool among CRUD siblings, but lacks exclusion criteria or context for appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Insert a Gutenberg block pattern preset (hero, faq, columns) into a page/post
| Name | Required | Description | Default |
|---|---|---|---|
| preset | Yes | Built-in block pattern preset | |
| page_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the core insertion action but does not mention whether the pattern is appended or replaces existing content, whether editing permissions are required, or what happens on failure. This is a mutation operation with no side-effect or reversibility context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler; the verb, resource, target, and preset examples all earn their place. It is easy for an agent to scan quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with an enum, the description plus schema is mostly sufficient to invoke it correctly. However, with no annotations and no output schema, it leaves moderate gaps around the insertion behavior, such as where the pattern lands, whether content is overwritten, and required permissions, so it is only minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50% because page_id has no description, but the tool description maps page_id to the target page/post and clarifies preset as a built-in block pattern. It adds semantic context to the undocumented parameter, even though the preset examples duplicate the schema enum.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action (insert), a distinct resource (Gutenberg block pattern preset), and the target (a page/post), and enumerates the available presets. This makes the tool clearly distinguishable from sibling content tools like wp_update_block or wp_create_post without needing to open the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states what the tool does but gives no guidance on when to choose it over alternatives, and no exclusions or prerequisites. An agent cannot tell whether this should be used instead of wp_update_block for existing content, wp_create_post for new posts, or Elementor insertion tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Gutenberg blocks on a page/post as a flat index with blockName, path, and attributes preview
| Name | Required | Description | Default |
|---|---|---|---|
| page_id | Yes | WordPress page or post ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral disclosure burden. It does disclose the return format in useful detail (blockName, path, attributes preview) and the verb 'List' implies a read-only operation, but it does not mention limitations, edge cases, or any side effects. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the core action and resource, then compresses the output contract into a compact list. Every word adds value, and there is no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a single well-documented parameter and no output schema, so the description's mention of blockName, path, and attributes preview covers the return contract. It is complete enough for a simple read-only list operation, though 'path' could have been clarified further.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already fully documents page_id as the WordPress page or post ID. The description adds no new parameter-level meaning, but none is needed; the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action ('List') and a precise resource ('Gutenberg blocks on a page/post'), then specifies the exact output shape ('flat index with blockName, path, and attributes preview'). This clearly distinguishes it from sibling block-related tools like wp_update_block or wp_insert_block_pattern.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for inspecting blocks within a specific page or post, but it gives no explicit guidance on when to choose this over alternatives such as wp_get_page or wp_update_block. No exclusions, prerequisites, or alternative routing are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List WooCommerce Bookings products (requires WooCommerce Bookings plugin)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral disclosure burden. 'List' implies a read-only operation, and the plugin requirement is a useful precondition. However, it does not disclose what happens if the plugin is missing, whether any side effects occur, or what the response format looks like. This is a minor gap for a simple listing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action and resource, with a parenthetical prerequisite that earns its place. There is no redundancy or filler text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list tool with no output schema, the description reasonably conveys the resource type and the prerequisite plugin. It could have added a note about behavior when the plugin is inactive, but the simplicity of the tool keeps the gap small.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the baseline is 4. The description correctly adds no unnecessary parameter detail. There is nothing missing for an agent to invoke the tool with an empty arguments object.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'List WooCommerce Bookings products'. It clearly identifies the domain and the specialized resource type, and implicitly separates it from the generic wp_list_products sibling. However, it does not explicitly contrast itself with that sibling, so it falls short of a top score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear prerequisite: it requires the WooCommerce Bookings plugin. This provides context about when the tool is applicable. It does not mention alternatives or exclusions, but for a no-parameter listing tool, the plugin requirement is the main usage gate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List WordPress categories
| Name | Required | Description | Default |
|---|---|---|---|
| search | No | ||
| per_page | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must convey behavioral traits. It only says 'list', implying read-only, but omits details like pagination, sorting, authentication requirements, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two words, which is too brief. While concise, it lacks essential information, making it under-specified rather than efficiently front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema or annotations, the description should cover return format, pagination, and filtering behavior. It fails to provide sufficient context for an agent to understand its full use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the tool description does not elaborate on the parameters. 'per_page' and 'search' are not explained (e.g., per_page controls count, search filters by name), so the description adds no value over the field names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List WordPress categories' clearly states the verb (list) and resource (categories). It is specific and distinguishable from siblings like wp_list_tags or wp_list_pages by name, but lacks explicit differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, context, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List WordPress comments with optional status and post filters
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| status | No | Comment status filter | |
| post_id | No | Filter by post ID | |
| per_page | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description carries the full burden. It discloses that the tool lists comments but does not state pagination behavior, default comment statuses, result ordering, or authentication/authorization expectations. The read-only nature is only implicit in the word 'List'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no wasted words. The action, resource, and key filtering capability are all front-loaded efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, no annotations, and only 50% schema description coverage. The description does not clarify return format, pagination defaults, or status filter vocabulary, leaving meaningful gaps for an agent trying to invoke and interpret results correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds filter semantics by saying 'optional status and post filters', which maps to the documented `status` and `post_id` schema properties. However, `page` and `per_page` are undocumented in both the schema and the description, and no allowed status values or defaults are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('WordPress comments') and mentions optional filters. This clearly distinguishes it from mutation-focused sibling tools like wp_moderate_comment and wp_reply_to_comment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied: retrieving comments with optional filters. However, there is no explicit when-to-use guidance, no exclusions, and no mention of alternatives such as moderation or reply tools for comment-related mutations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List items of a custom post type with optional filters
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| search | No | ||
| status | No | ||
| per_page | No | ||
| post_type | Yes | Post type slug |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry the full behavioral disclosure burden. 'List' implies a read-only operation, but the description does not mention pagination behavior, default status scope, or whether results are limited. It adds no information beyond the verb itself about side effects or safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no fluff. It is front-loaded with the core action and resource, and every word contributes to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
As a listing tool with no output schema and minimal documentation, the description is too sparse. It does not clarify the position among the CPT item family (get/create/update/delete/list), nor explain the return format or pagination behavior. An agent would need to inspect the schema or guess to understand what 'items' entails and how filters affect results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20% (only post_type has a description). The phrase 'optional filters' is vague and does not enumerate or explain page, search, status, or per_page, nor how they interact. The description fails to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List items of a custom post type' clearly identifies the action (list), the resource (items of a custom post type), and distinguishes this from siblings like wp_get_cpt_item (single item), wp_list_posts (standard posts), and wp_list_pages (pages). The use of 'custom post type' provides specificity beyond a generic list tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a user wants to enumerate custom post type items, but it provides no explicit guidance about when to prefer this over wp_list_posts or wp_get_cpt_item. There are no stated alternatives or exclusions, leaving the selection inference entirely to the name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List scheduled WordPress cron events (read-only)
| Name | Required | Description | Default |
|---|---|---|---|
| hook | No | Filter by cron hook name | |
| page | No | ||
| per_page | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden. Explicitly stating '(read-only)' is a meaningful behavioral disclosure that signals no state changes. It does not go further into pagination behavior or response details, but for a simple list operation the read-only guarantee is the key behavioral fact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short, front-loaded sentence with no filler. Every word earns its place, and the read-only qualifier is included without bloating the text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple list operation, but there are gaps: no output schema, no clarification of hook filter behavior, and no pagination semantics. The agent can call it with zero parameters, but would lack details about response shape and filter matching when using the optional parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%, with only 'hook' explained. The description adds no parameter-level meaning; 'page' and 'per_page' are left to their names and numeric constraints. Because coverage is low, the description should have compensated, but it does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('List'), a specific resource ('scheduled WordPress cron events'), and immediately disambiguates it from the many other wp_list_* sibling tools. An agent can tell this apart from wp_list_pages, wp_list_posts, or wp_list_themes without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for reading scheduled cron events but provides no explicit when-to-use or when-not-to-use guidance. It does not name alternatives or state exclusions, so an agent has to infer the use case from the name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List custom MCP outbound webhooks configured on the site
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. 'List' implies a non-mutating read operation, and 'configured on the site' adds useful scope. However, it does not disclose whether permissions are required, whether disabled webhooks are included, or whether any pagination or limits apply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word contributes meaning: 'List', 'custom MCP outbound', and 'configured on the site' all clarify the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema list tool, the description is largely complete. It names the exact resource being listed. The only minor gap is that it does not explicitly describe the return format, but for a simple list tool this is reasonably inferable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters and the schema description coverage is 100%, so there are no parameter meanings to add. A 0-parameter tool needs no parameter explanation, and the description accurately describes the list operation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and a specific resource ('custom MCP outbound webhooks configured on the site'). It clearly distinguishes this tool from sibling tools like wp_get_custom_webhook, wp_create_custom_webhook, wp_update_custom_webhook, and wp_delete_custom_webhook by indicating it lists rather than operates on a single webhook.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance about when to use this tool versus alternatives. While it is obvious this lists custom MCP outbound webhooks, it does not mention related tools such as wp_list_webhook_deliveries, wp_list_woocommerce_webhooks, or wp_list_form_webhooks, nor does it state conditions for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Ninja Forms on the site (requires Ninja Forms plugin)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. 'Requires Ninja Forms plugin' is a useful dependency disclosure, and 'List' implies read-only enumeration. It does not state what happens if the plugin is missing or describe the returned data, but the basic behavior for a simple list operation is conveyed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action, resource, and plugin prerequisite without any unnecessary words. Every part adds useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list operation, this description is largely complete: it names what is listed and the required condition. It does not explain the output format or failure behavior when the plugin is absent, but the simplicity of the tool and absence of parameters reduce the need for more detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so there are no parameter semantics for the description to clarify. The zero-parameter baseline applies, and no additional parameter-level detail is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('List') and resource ('Ninja Forms on the site'), and names the required plugin. This differentiates it from getters and related tools like wp_get_form, wp_list_form_submissions, and wp_list_form_webhooks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear prerequisite: the Ninja Forms plugin must be installed. However, it does not explicitly contrast this tool with alternatives such as wp_get_form or wp_list_form_submissions, so when-to-use guidance is primarily implied by the name and phrasing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List submissions for a Ninja Form
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Form ID | |
| page | No | ||
| per_page | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It only states that it lists submissions, without disclosing return format, pagination behavior, ordering, or possible side effects. 'List' implies read-only, but this is left implicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word contributes meaning, and it delivers the core action efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a minimal description with no output schema and no annotation context. It omits pagination parameter semantics, return value shape, and the relationship to form-related sibling tools like wp_list_forms. Basic invocation is possible, but an agent is left guessing about important details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only 'id' is described in the schema (as 'Form ID'), and the description does not explain 'page' or 'per_page'. With schema description coverage at only 33%, the description should compensate by clarifying the pagination parameters, but it does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('submissions for a Ninja Form'), making the tool's purpose immediately clear. It also distinguishes itself from all sibling tools, none of which mention submissions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, no mention that a form ID must first be obtained via wp_list_forms or wp_get_form, and no exclusions or fallback tools. The usage context is entirely unstated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Ninja Forms webhook actions on a form (requires Ninja Forms)
| Name | Required | Description | Default |
|---|---|---|---|
| form_id | Yes | Ninja Form ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden of behavioral disclosure. 'List' reasonably signals a read-only operation and the Ninja Forms prerequisite is disclosed, but the description does not cover failure behavior (e.g., what happens when Ninja Forms is absent or the form_id does not exist) or the return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler; the verb and resource lead. The only minor flaw is the redundancy of 'Ninja Forms' appearing twice, once in the resource phrase and once as the prerequisite parenthetical.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter list tool with 100% schema coverage, the description is nearly sufficient: the agent knows what to call and which ID to pass. However, with no output schema and no annotations, the description does not clarify what a returned 'webhook action' looks like or how prerequisite failures surface, leaving mild ambiguity about the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — the single required parameter form_id is already documented as 'Ninja Form ID' in the schema. The description adds no parameter-level detail, so the baseline of 3 applies; nothing more is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and a specific resource ('Ninja Forms webhook actions on a form'), and the 'Ninja Forms' + 'on a form' qualifiers differentiate it from siblings like wp_list_custom_webhooks and wp_list_woocommerce_webhooks. The term 'webhook actions' is slightly ambiguous — it is not clear whether it lists configured webhook endpoints or available action topics — which keeps it from a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no when-to-use or when-not-to-use guidance and names no alternatives. The parenthetical '(requires Ninja Forms)' hints at a prerequisite but does not help an agent choose between this tool and the many webhook-related siblings such as wp_list_custom_webhooks, wp_list_webhook_topics, or wp_list_woocommerce_webhooks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List WordPress media library items
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| search | No | ||
| per_page | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not mention any behavioral traits such as pagination, ordering, or response format. No annotations are provided to fill gaps. The tool may return a list of media items, but details like maximum results, caching, or error behavior are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It is front-loaded with the action and resource. However, it could be slightly longer to include critical details without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is severely incomplete given no annotations, no output schema, and three parameters with no documented meaning. The tool likely returns a list of media objects, but return structure, pagination metadata, and default behavior are entirely omitted. A tool with this complexity requires more explanation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no meaning to any of the 3 parameters (per_page, page, search). With schema description coverage at 0%, the description fails to compensate. The schema itself provides basic names and types, but users must infer usage from the schema alone. The description does not explain that 'search' filters by title or that 'per_page' and 'page' enable pagination.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'WordPress media library items'. It is specific enough to distinguish from sibling tools like 'wp_get_media' which retrieves a single item. However, it could be more precise (e.g., 'list all media items with pagination and search').
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'wp_get_media' or when not to use it. The description lacks context about typical use cases or prerequisites. Sibling tools exist for getting, uploading, updating, and deleting media, but no differentiation is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List WooCommerce orders with optional filters
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| search | No | ||
| status | No | Order status or 'any' | |
| per_page | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states that the tool lists orders, which implies a read operation, but it does not disclose pagination behavior, the meaning of status 'any', search scope, or what the response contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no wasted words. It immediately communicates the core operation and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and thin parameter documentation, the description is not complete enough for an agent to reliably understand pagination, filter meanings, or result behavior. An agent could make a basic call, but meaningful use of the available parameters requires inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25%, with only 'status' documented. The description says 'optional filters' but does not explain page, search, or per_page semantics, so it fails to compensate for the schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'List WooCommerce orders'. It clearly identifies the operation, though 'with optional filters' is vague about which filters and does not explicitly differentiate from sibling wp_get_order beyond the list/get distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. The description does not mention that wp_get_order should be used for a single order, nor does it explain when filters should be used or what the default behavior is.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List WordPress pages with optional filters
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| search | No | ||
| status | No | Filter by post status | |
| per_page | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description fails to disclose important behaviors like default filters, pagination limits, or whether private/draft pages are included. Only a high-level purpose is given.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short phrase, which is concise but lacks critical details. It is front-loaded but sacrifices completeness for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and 4 parameters with low schema coverage. The description does not explain pagination, response format, or how filters interact, making it severely incomplete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 25% description coverage (only 'status' is described). The description adds no extra meaning beyond 'optional filters', leaving three parameters (per_page, page, search) without explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list) and resource (WordPress pages) with optional filters, which distinguishes it from sibling tools like wp_list_posts or wp_list_media. However, it does not clarify that pages are a specific post type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as wp_get_page for a single page or wp_list_posts for posts. Missing context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List installed WordPress plugins (read-only)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It states 'read-only', indicating no destructive actions, which is a key behavioral trait. However, it does not disclose other aspects like return format, pagination, or potential errors. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of three words, front-loading the verb and resource. Every word earns its place with no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal and does not detail what the returned data contains (e.g., plugin names, versions). Without an output schema, the agent may be uncertain about the response structure. For a simple listing tool, this is a noticeable gap, though the intent is clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100% (trivially). Per guidelines, baseline is 4. The description adds no parameter semantics, but none are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and resource 'installed WordPress plugins', clearly distinguishing it from sibling tools that create, update, or delete other resources like pages or posts. The 'read-only' qualifier further clarifies its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for listing plugins and is safe (read-only). While it doesn't explicitly mention when to use it over alternatives, the sibling tools are mostly for other actions or resources, making it clear this is the go-to for plugin listing. No exclusions or conditions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List WordPress posts with optional filters
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| search | No | ||
| status | No | ||
| per_page | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must disclose behaviors. It does not mention pagination defaults, sorting order, or that the response contains an array of post objects. This lack of behavioral detail increases the risk of misuse.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, making it concise and front-loaded. However, it is too brief and omits crucial details; conciseness sacrifices completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 parameters, no output schema, and no annotations, the description is insufficient. It does not explain return format, pagination behavior, or default values. Given sibling tools with similar patterns, more context is needed for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description adds no parameter explanations. While parameter names (status, per_page, page, search) are somewhat self-explanatory, the description fails to clarify their roles or constraints, leaving the AI to infer.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'WordPress posts', and the optional filters are mentioned. It distinguishes from siblings like wp_list_pages and wp_list_media, which list different content types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., wp_list_pages). There is no mention of prerequisites, when not to use, or context for filtering. The description is purely definitional.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List allowed custom post types available via MCP
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. The verb 'List' implies a safe read operation, and the qualifiers 'allowed' and 'available via MCP' disclose a filtering behavior beyond the bare tool name. However, the description doesn't clarify what 'allowed' means, whether built-in post types are included in addition to custom ones, or what the returned structure looks like.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single 8-word sentence with the verb front-loaded and no filler. The only flaw is a mild redundancy between 'allowed' and 'available via MCP', which both convey roughly the same MCP-scoping idea, but this is minor and doesn't impede readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless list operation with no annotations and no output schema, the description is mostly adequate, but it leaves ambiguity about whether built-in post types are part of the result set and what criterion defines 'allowed'. An agent can invoke the tool correctly, but may misjudge the scope of what it returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, so the empty schema trivially covers everything and the baseline of 4 applies. The description adds relevant semantic content by scoping the result set to 'allowed custom post types', which is the meaningful information an agent needs for a parameterless list operation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') with a clear resource ('custom post types') and a scoping constraint ('allowed... available via MCP'). It is distinguishable from siblings like wp_list_posts (posts vs post types) and wp_list_taxonomies (taxonomies vs post types). However, it doesn't explicitly disambiguate from those siblings, and the meaning of 'allowed' is left somewhat open.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives such as wp_list_posts, wp_list_cpt_items, or wp_list_taxonomies. There are no exclusions, conditions, or references to sibling tools. The only usage signal is implicit in the resource name itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List WooCommerce products with optional filters
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| search | No | ||
| status | No | Product status or 'any' | |
| per_page | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. "List" implies a read-only operation and "optional filters" suggests filtering, but the description does not disclose pagination behavior, default values, response shape, or whether any statuses or search terms have special semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one front-loaded sentence with no wasted words. It states the primary action and resource immediately. It is concise, though somewhat under-specified, which prevents a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations, no output schema, and sparse parameter documentation, this one-line description is not fully complete. It omits filter semantics, pagination behavior, and return expectations, leaving important context to inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25%, covering just the status parameter. The description adds only the generic phrase "optional filters" and does not explain page, search, per_page, or the meaning of status values beyond the schema. It fails to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: "List WooCommerce products." This distinguishes it from single-product tools like wp_get_product and from wp_list_booking_products. However, "optional filters" is vague and does not identify which filters are available, so it falls just short of being fully specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as wp_get_product for a single product or wp_list_booking_products for booking products. No exclusions, prerequisites, or scenarios are given, so the agent must infer usage entirely from the name and minimal description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List built-in URL redirects managed by WP MCP Control
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the full burden. It implies a read-only listing but provides no details on behavioral traits like return format, pagination, ordering, or safety. Minimal beyond stating the operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, concise, front-loaded with the verb and resource. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple list tool with no parameters and no output schema, but lacks detail on scope (all redirects or subset), format, or any special behavior. Could be more helpful for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema coverage is 100% (vacuously). The description adds context about 'built-in URL redirects' but no parameter info needed. Per calibration guidelines, baseline is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists 'built-in URL redirects managed by WP MCP Control', using a specific verb ('List') and resource ('built-in URL redirects'). It distinguishes from sibling tools like wp_create_redirect, wp_update_redirect, and wp_delete_redirect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., wp_search_content or other redirect tools). Lacks explicit context for usage or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List WordPress revisions for a post or page
| Name | Required | Description | Default |
|---|---|---|---|
| post_id | Yes | Post or page ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden of behavioral disclosure. It only states that the tool lists revisions and does not mention ordering, pagination, whether autosaves are included, or what fields the returned revisions contain. The word 'List' weakly implies a read-only operation, but nothing beyond that is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that directly states what the tool does. It contains no filler, no redundant restatement of the tool name, and it front-loads the core operation and target resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, with one required parameter, and the description covers the primary purpose. However, because there is no output schema and no annotations, the description does not explain what the returned revision list looks like, whether it is sorted, or whether special cases like autosaves are included. These are clear but not critical gaps for a low-complexity list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter post_id is fully described in the schema as 'Post or page ID', and the description repeats this exact scoping. Schema description coverage is 100%, so the description adds no meaningful semantic value beyond what the schema already provides. This matches the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and a clear resource ('WordPress revisions for a post or page'), making it easy to identify. It also implicitly distinguishes this tool from siblings like wp_get_revision, wp_get_revision_diff, and wp_restore_revision, which target a single revision or a different operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used when an agent needs all revisions for a given post or page, but it does not explicitly contrast it with alternative revision-related tools. An agent can infer the usage from the verb and resource, but there is no direct when-to-use or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List WordPress roles and their capabilities
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full disclosure burden. It reveals the main behavior (listing roles and their capabilities), but does not state that the operation is read-only/safe, what the exact return shape is, or whether any WordPress permissions are required. 'List' implies no side effects, but additional context would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler. Every word adds meaning, and it is appropriately sized for a tool of this simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (no parameters, no output schema), and the description states the core function and result. However, because there is no output schema and no annotations, a bit more context—such as confirming it returns the complete set of roles or noting that it is read-only—would make it fully complete for an agent. The current description is minimally viable but sparse.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the input schema is trivially complete (100% coverage). The description does not need to explain any parameter semantics; the baseline for zero-parameter tools is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and a specific resource ('WordPress roles') plus the included detail ('their capabilities'). This makes the tool's function immediately clear and distinguishes it from sibling listing tools like wp_list_users or wp_list_themes by naming a unique resource category.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance about when to choose this tool over alternatives, no preconditions, and no exclusions. It only states what the tool does, leaving the agent to infer usage entirely from the name and sibling context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List registered WordPress widget sidebars
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. 'List' implies a non-destructive read operation, but the description does not disclose return format, whether an empty list is possible, or any other behavioral detail. It is adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no filler. It front-loads the action and resource, and every word contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list tool with no output schema, this description is mostly complete. It tells the agent what action is performed and on what resource. It could mention what fields each sidebar entry contains, but that is not essential for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the input schema is already complete with 100% coverage. The description adds no parameter details, but none are needed. Baseline 4 is appropriate for a zero-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and a precise resource ('registered WordPress widget sidebars'), clearly indicating what the tool returns. The word 'registered' adds WordPress-specific context, and the resource name 'sidebars' differentiates it from sibling tools like wp_list_widget_instances.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as wp_list_widget_instances. There is no mention of scenarios or exclusions, so the agent must infer usage solely from the tool name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List WordPress tags
| Name | Required | Description | Default |
|---|---|---|---|
| search | No | ||
| per_page | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It says 'list', implying a read-only operation, but it does not specify pagination behavior, default results, whether it returns all tags, or any side effects. No details on search semantics or performance considerations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (3 words), which is concise, but it omits essential information. It is not 'appropriately sized' because it fails to cover parameter semantics or usage context, making it insufficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema, no annotations, and incomplete parameter documentation, the description is severely under-specified. It does not communicate what the tool returns, how to paginate, or what the search parameter filters on, leaving the agent with significant ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, and the tool description adds no meaning to the parameters per_page and search. The agent is left to guess their purpose and valid values. For a tool with two parameters, this is a critical gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and resource 'WordPress tags', which explicitly identifies the tool's action and target. However, it does not distinguish from sibling tools like wp_list_categories or wp_list_pages, which have similar list operations for different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like wp_list_categories or wp_create_tag. It lacks any contextual hints about prerequisites, typical scenarios, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all public WordPress taxonomies with object types
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It clarifies a meaningful behavioral trait: only public taxonomies are returned, and object types are included. The verb 'List' also implies a read-only operation, though the description does not explicitly state that no changes are made or mention any auth/rate-limit considerations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no filler. It front-loads the verb and resource, then adds the only key qualifier ('public' and 'with object types').
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter list operation without an output schema, the description covers the essential information: what is listed (taxonomies), the scope (public), and what is included (object types). It omits details like ordering or exact return representation, but these are minor for such a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the baseline is 4. The description's mention of 'public' and 'object types' relates to output scope rather than parameter semantics, so no additional parameter guidance is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and names a precise resource ('all public WordPress taxonomies') with a useful detail ('with object types'). This clearly differentiates it from sibling tools like wp_list_taxonomy_terms, wp_list_categories, and wp_list_post_types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied: use this when you need the full list of public taxonomies. However, there is no explicit when-to-use/when-not-to-use guidance or mention of alternatives such as wp_list_taxonomy_terms for terms within a taxonomy, leaving the agent to infer selection from the name and description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List terms for a taxonomy
| Name | Required | Description | Default |
|---|---|---|---|
| search | No | ||
| per_page | No | ||
| taxonomy | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full burden of behavioral disclosure. It reveals only that this is a listing operation, and omits behavior such as pagination via per_page, search behavior, what happens when the taxonomy does not exist, or the shape of the returned term list.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant words. It is appropriately compact, though it could include additional parameter context without becoming bloated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three parameters, no output schema, and no annotations, the description is too thin. It does not clarify how search works, how pagination is handled, which taxonomy identifies the source, or how the response is structured, leaving meaningful gaps for an agent deciding how to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not compensate by explaining the required taxonomy parameter or the optional search and per_page parameters. An agent must infer the meaning of all three parameters from their names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and a clear resource ('terms for a taxonomy'), which conveys the core operation. It is distinguishable from siblings like wp_list_taxonomies and wp_create_taxonomy_term, though it does not spell out what kinds of terms or which taxonomies are covered.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool instead of related tools such as wp_list_taxonomies, wp_list_categories, or wp_list_tags. The description states only the action and gives no context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List installed WordPress themes (read-only)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It indicates read-only, but does not specify what the output looks like (e.g., a list of names, objects, or metadata). For a tool with no parameters, the return format is key behavioral info.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short sentence that front-loads the core action and resource. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema or annotations, the description is minimally adequate. It identifies the tool's purpose but omits output structure or any behavioral nuance beyond read-only.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the schema covers everything. The description adds no parameter info, but none is needed. Baseline for 0 params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'installed WordPress themes', with '(read-only)' clarifying it's non-mutating. This distinguishes it from sibling list tools targeting different entities like plugins, pages, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool vs alternatives. Usage is implied: use when you need a list of themes. No exclusion or guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List WordPress users with optional role and search filters
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| role | No | ||
| search | No | ||
| per_page | No | ||
| include_email | No | Include email addresses in response |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It implies a read-only list operation but does not state pagination defaults, field limitations, whether email addresses are excluded by default, or any authorization requirements. The agent is left without key behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence that front-loads the action and resource. No wasted words, though it misses opportunities to add higher-value parameter or behavior details without becoming long.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter tool with no annotations and no output schema, the description is too thin. It omits pagination, default response fields, filter semantics, and any return format guidance. An agent would need to guess or make unsafe assumptions to call it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20% (only include_email has a description). The description mentions role and search filters but does not clarify role format, search matching criteria, or pagination semantics for page and per_page. It does not compensate sufficiently for the schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'List WordPress users'. The optional role and search filters further define scope and clearly distinguish it from sibling tools like wp_get_user or wp_create_user. No ambiguity about what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as wp_get_user for a single user, or when to apply specific filters. It does not mention exclusions or prior conditions, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List delivery log entries for a custom MCP webhook
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Webhook ID | |
| page | No | ||
| per_page | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the behavioral burden; 'List' clearly signals a read-only operation with no destructive side effects. However, it does not disclose pagination behavior, ordering, or what a delivery log entry contains, so transparency is only partially covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It states the operation and target resource efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and only 33% parameter coverage, the description is enough for a basic call (provide a webhook id) but not enough for an agent to know what a delivery log entry looks like, how results are paginated, or how this tool differs from listing webhooks. It is minimally viable but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%; 'id' is described as 'Webhook ID' in the schema, and the description adds only the 'custom MCP webhook' qualifier. The optional page and per_page parameters are left undocumented in both schema and description, so an agent must infer pagination semantics from their names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('delivery log entries') and scopes it to a custom MCP webhook, clearly separating it from tools that list webhooks themselves or webhook topics. It does not explicitly contrast with siblings, but the object of the action is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool instead of related webhook tools, such as wp_list_custom_webhooks, wp_get_custom_webhook, or wp_test_custom_webhook. The description leaves the selection criteria entirely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List available custom MCP webhook event topics (content, WC, forms, cache, etc.)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, and it only states that the tool 'lists' topics, implying a read-only operation. It does not describe the output format (array of name strings vs. objects with metadata), ordering, or how the topics map to webhook creation. Nothing is misleading, but little behavioral context is added beyond the obvious semantics of 'list'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with zero wasted words. The verb and resource are front-loaded, and the parenthetical examples earn their place by disambiguating the resource without adding bulk. This is appropriately sized for a zero-parameter listing tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple, zero-parameter discovery tool: the description names the resource and gives examples. However, since there is no output schema, the description is the only place to disclose what the returned topics look like and how they feed downstream tools like wp_create_custom_webhook; that connection is absent, leaving a real gap an agent would encounter when using the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description adds useful domain context by enumerating example topic categories (content, WC, forms, cache), which helps an agent interpret what 'topics' means even though no parameters require documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('List available custom MCP webhook event topics') and adds parenthetical examples (content, WC, forms, cache) that clarify what a 'topic' is. It is distinguishable from siblings like wp_list_custom_webhooks, which list webhook configurations rather than event topics, though this differentiation is implicit rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to call this tool versus alternatives. It does not mention that the returned topics are meant to be consumed by wp_create_custom_webhook, nor does it contrast with wp_list_custom_webhooks or wp_list_webhook_deliveries. The usage context is only loosely implied by the tool name and sibling set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List widget instances across sidebars (text and custom_html widgets are editable)
| Name | Required | Description | Default |
|---|---|---|---|
| sidebar | No | Filter by sidebar ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the behavioral burden. 'List' implies a read-only operation, and the editable-widget parenthetical is useful, but the description omits output shape, pagination, and whether inactive or empty sidebars are included.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence communicates the core action and scope. The parenthetical is compact and informative without wasting words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one optional parameter, but there is no output schema and the description does not explain what fields an agent should expect in the returned widget instances. This leaves minor but real ambiguity for correct downstream use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents the only parameter ('sidebar') with 100% coverage as 'Filter by sidebar ID'. The description adds no additional meaning about parameter formatting or accepted values, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('List') and resource ('widget instances'') with scope across sidebars. The parenthetical about text and custom_html widgets being editable adds useful differentiation from simpler list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for listing widget instances, especially editable ones, but it never explicitly says when to use this versus wp_list_sidebars or wp_update_widget_instance. No exclusions or alternative routing are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List WooCommerce native webhooks (product/order topics)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the disclosure burden. It communicates a read-only intent through 'List' and scopes the result to native webhooks with product/order topics, which prevents confusion with custom/form webhooks. However, it does not mention output shape, pagination, permissions, or any other behavior, leaving the agent to infer details beyond the minimal operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The entire description is a single front-loaded sentence with no filler. Every element ('List', 'WooCommerce native webhooks', 'product/order topics') contributes to scope, so it earns a high conciseness score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter read-only tool, the description is minimally sufficient: an agent knows exactly which resource is being listed and that it is the native, not custom or form, variant. Clear gaps remain, however, because there is no output schema and no description of return values or pagination, and the relationship to the many sibling webhook tools is only implicit through the word 'native'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is empty and schema coverage is 100%, so there are no parameter semantics to document. With zero parameters, the description does not need to compensate for any parameter gaps; the baseline 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') plus a resource ('WooCommerce native webhooks'), and the parenthetical '(product/order topics)' narrows the scope. The word 'native' distinguishes it from sibling custom-webhook and form-webhook listers, so an agent can tell this tool apart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description identifies the target resource ('native webhooks') and thereby implies the WooCommerce-webhook context, but it never states when to prefer this tool over sibling listers like wp_list_custom_webhooks or wp_list_form_webhooks, nor does it specify exclusions. The 'native' qualifier gives some context, so the guidance is present but mostly implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Moderate a comment: approve, hold, spam, or trash. confirm required for spam/trash in safe mode.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Comment ID | |
| status | Yes | Moderation action | |
| confirm | No | Required for spam/trash when safe mode is enabled |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It mentions the 'confirm required for spam/trash in safe mode' caveat, but this merely repeats the schema's confirm parameter description. It does not explain side effects, reversibility, permission requirements, or what happens in non-safe mode.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loads the core purpose, and contains no filler. The enum values and the confirm caveat are both essential and efficiently presented.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and the schema covers all parameters, but the description leaves ambiguity around 'safe mode,' such as when it is active or what response to expect. Given no output schema and no annotations, slightly more context about the tool's behavior and safe mode semantics would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents id, status, and confirm. The description adds no new parameter meaning beyond restating the confirm requirement already present in the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Moderate a comment' and enumerates the exact actions ('approve, hold, spam, or trash'). This clearly distinguishes it from sibling comment tools like wp_reply_to_comment, which is about replying rather than changing moderation status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives such as wp_reply_to_comment or wp_list_comments. It does not state exclusions or mention a sibling tool that handles different comment operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Purge site cache (LiteSpeed, WP Rocket, W3TC, etc.). confirm:true required when safe mode is enabled.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No | Required when safe mode is enabled |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the behavioral disclosure burden. It does disclose that confirmation is required when safe mode is enabled, which is a meaningful guardrail. However, it does not explain what 'safe mode' is, whether the purge is destructive to all cache layers, or what side effects to expect, leaving some behavioral uncertainty.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences convey the tool's purpose, scope, and the key invocation constraint. There is no filler or redundant elaboration; every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter cache purge tool with no output schema, the description provides the core information needed to invoke it. The only notable gap is the undefined 'safe mode' term, which may be ambiguous without further context, but overall the tool is adequately described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents the 'confirm' parameter. The description adds the exact required value ('confirm:true'), which goes slightly beyond the schema's 'Required when safe mode is enabled' by clarifying that the boolean must be true rather than merely present.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Purge') and resource ('site cache'), and it enumerates the supported cache plugins (LiteSpeed, WP Rocket, W3TC, etc.). This is specific enough for an agent to distinguish it from the sibling tools, none of which are cache-purge operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: whenever the site cache needs clearing. It does not explicitly name alternatives or exclusion conditions, but the safe-mode confirmation requirement provides some contextual guidance for invocation. It would be stronger if it said 'use when cache must be invalidated' or listed cases where a full purge is not appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a WooCommerce order refund. confirm:true required. Requires wp_mcp_allow_wc_refunds setting.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Order ID | |
| amount | No | Refund amount (defaults to order total) | |
| reason | No | ||
| confirm | No | Required when safe mode is enabled | |
| restock | No | Restock refunded items |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It usefully reveals the confirm requirement and the configuration prerequisite, indicating this is a guarded mutation. However, it does not describe the financial side effects, order status impact, or restocking behavior, and its blanket 'confirm:true required' claim is at odds with the schema's conditional 'Required when safe mode is enabled'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short, purposeful sentences. It front-loads the core action, then states the key requirements without filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a financial mutation tool with no annotations and no output schema, this description is minimally viable: it names the action and the two essential prerequisites. It still lacks context about safe-mode behavior, refund consequences, and what happens after invocation, which leaves meaningful gaps for an agent deciding whether and how to call it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80%, so the baseline is 3. The description adds little beyond the schema; 'confirm:true required' restates a parameter-level requirement that the schema already documents conditionally. The config setting is helpful context but is not a parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Create a WooCommerce order refund.' This clearly identifies the action and target, and the tool name reinforces it. It does not explicitly contrast with similar order-related siblings like wp_update_order, so it stops short of full differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides important preconditions: 'confirm:true required' and the required wp_mcp_allow_wc_refunds setting. However, it does not explicitly state when to choose this tool over alternatives such as wp_update_order or wp_add_order_note; usage context is only implied by the refund-focused purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reply to a comment as the site admin
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Parent comment ID | |
| content | Yes | Reply content (HTML allowed) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must disclose side effects on its own. The phrase 'as the site admin' adds authorship context, but the description doesn't state whether the reply is immediately published, whether it requires an existing comment, or what the response looks like. For a write operation this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler, front-loading the verb and object. Every word contributes to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, important context is missing: the return value, publication behavior, and error conditions are unstated. Though the parameters are well documented, the operation's effects are not fully described, leaving an agent to guess about expected outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes both required parameters clearly: id as parent comment ID and content as reply content with HTML allowed, giving 100% coverage. The description adds no further parameter-level meaning, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'Reply' and the resource 'comment', making the core action clear. It doesn't explicitly differentiate from sibling tools like wp_moderate_comment or wp_list_comments, but the phrasing leaves little ambiguity about the operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this versus alternatives such as wp_moderate_comment or wp_list_comments. The description offers no context about prerequisites like an existing comment or admin permissions, and no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restore a post/page to a previous revision. confirm:true required when safe mode is enabled.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No | Required when safe mode is enabled | |
| revision_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the safe-mode confirmation requirement, which is a useful behavioral trait. However, it does not state that restoring overwrites current content, whether the change is reversible, or what permissions are needed—so transparency is partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The first sentence is front-loaded and unambiguous. The second sentence is short but repeats the confirm requirement already in the schema, so it earns only partial credit for conciseness; otherwise there is no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with no annotations or output schema, the description gives the core purpose and a safety condition. It is missing guidance on where revision_id comes from (e.g., wp_list_revisions), the destructive overwrite behavior, and what the response will be. This makes it minimally viable but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%; only confirm has a schema description. The description's phrase 'to a previous revision' adds semantic context to revision_id, indicating it identifies the target revision, and it restates the confirm requirement. It does not explain how to obtain revision_id or the safe-mode trigger, so value is modest.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Restore' with a clear resource: 'a post/page to a previous revision.' This distinguishes it from sibling revision tools like wp_list_revisions, wp_get_revision, and wp_get_revision_diff, which do not mutate content. No tautology or vagueness.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The only guidance is the conditional 'confirm:true required when safe mode is enabled,' which is a prerequisite for some invocations but not a use-case comparison. There is no explicit statement of when to use this tool versus alternatives, such as listing or diffing revisions first; the use case is merely implied by the verb 'restore.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restore a previous content snapshot before an update/delete
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | Yes | Must be true to confirm restore | |
| snapshot_id | Yes | Snapshot ID from activity log |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It does not mention that restoring overwrites current content or that confirmation is required, though the confirm parameter is present. The description is minimal and does not clarify side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no extraneous words. However, it could benefit from additional structure to separate purpose and usage details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and lack of output schema or annotations, the description is too brief. It does not explain how to obtain the snapshot_id, what happens after restore, or any error conditions. More context is needed for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% as both parameters have descriptions in the input schema. The tool description adds no additional meaning beyond what the schema already provides, so it meets the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Restore) and the resource (a previous content snapshot). It is specific and distinguishes from sibling tools as no other snapshot-related tool exists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description lacks context on prerequisites or when restoration is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search across WordPress pages, posts, media, categories, and tags
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | Search query | |
| status | No | any | |
| post_type | No | Types to search: page, post, attachment, category, tag | |
| date_after | No | ||
| date_before | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states 'Search across...' but does not disclose that the tool is read-only, or any behavioral traits like idempotency, permissions needed, or side effects. The description fails to add behavioral context beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. It is front-loaded with the action verb 'Search' and immediately specifies the scope. Every part of the sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters including query, filters, and limit, the description only lists content types. It does not explain query usage, date filtering, status, or pagination. No output schema exists, so the description needed to provide more completeness for agent invocation. It is inadequate for the complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 33% (only query and post_type have descriptions). The overall description does not mention any parameter details or provide additional meaning beyond the schema. With low schema coverage, the description should compensate, but it only lists content types without parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches across multiple WordPress content types (pages, posts, media, categories, tags), using a specific verb ('Search') and resource list. It distinguishes from sibling CRUD tools (create, delete, update) by being a search operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for searching content but does not explicitly state when to use it versus alternatives. No exclusions or alternative tool references are provided. Sibling tools are mostly CRUD, so context is clear but guidance is lacking.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get security posture: safe mode, dry run, rate limits, IP allowlist, token age, CORS settings
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, this description is the only behavioral signal. It communicates a read-only intent and the data domains that will be reported, but it does not disclose return format, permissions, or any potential side effects. The absence of an output schema increases the burden that this short description only partially meets.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One efficient, front-loaded sentence with a scannable colon-separated list. No filler or repetition of the tool name beyond the necessary verb.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only tool, invocation is simple, and the listed categories give a reasonable sense of what will be returned. However, there is no output schema and the description does not specify the shape or interpretation of the returned values, nor how posture may be represented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero parameters, so there is nothing for the description to document. Per the rubric's baseline for zero-param tools, this is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Get') and a concrete resource ('security posture'), then enumerates the contained data: safe mode, dry run, rate limits, IP allowlist, token age, CORS settings. It is clear and distinct from the sibling getters, though it does not explicitly contrast itself with wp_health_check or wp_site_audit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to choose this tool over related diagnostics like wp_health_check, wp_site_audit, or wp_get_settings. No context, exclusions, or alternative tools are mentioned, so an agent must infer usage solely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run site content audit: empty pages, missing alt text, redirect loops, draft backlog, SEO issues
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden of behavioral disclosure. It says an audit is run and lists audited areas, but it does not state whether the operation is read-only, whether it modifies or fixes anything, what the output looks like, or whether there are performance or safety implications. The 'audit' wording implies no side effects, but this is not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tightly written sentence that front-loads the action and resource, then efficiently enumerates five audit categories. Every word adds value and there is no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool, the description covers the main operational scope well, listing the audit categories. However, there is no output schema and no description of the return format, severity levels, or whether the audit includes remediation recommendations. Also, because 'SEO issues' overlaps directly with the sibling wp_audit_seo tool, the absence of a clarifying comparison leaves a meaningful completeness gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema description coverage is vacuously 100%. With no parameters, the description does not need to explain parameter meaning. The description still adds useful context about the scope of the audit, which is sufficient for a parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Run'), a clear resource ('site content audit'), and enumerates concrete audit dimensions: empty pages, missing alt text, redirect loops, draft backlog, and SEO issues. This distinguishes it from related siblings like wp_audit_seo, which is narrower in scope, and wp_health_check, which focuses on system health rather than content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when a broad content audit is needed), but it provides no explicit guidance about when not to use it or which alternatives to choose. In particular, it does not clarify how wp_site_audit relates to the overlapping wp_audit_seo tool, leaving the agent to infer the distinction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a test ping to a custom MCP webhook and return delivery result. confirm:true required when safe mode is on.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Webhook ID | |
| confirm | No | Required when safe mode is enabled |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full transparency burden. It discloses that the tool sends an external test ping and returns a delivery result, and that confirm must be true in safe mode. However, it does not explain safe mode semantics, possible side effects of the ping, or error/timeout behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action and resource, and no wasted words. The critical confirmation requirement is placed at the end without sacrificing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with no output schema or annotations, the description covers the core action and result. Still, 'delivery result' is vague, and safe mode is not defined, so an agent may not know what to expect in the response or exactly when confirmation is mandatory.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying that confirm must be set to true specifically, not merely present, when safe mode is enabled. This is a useful constraint beyond the schema's wording.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Send a test ping'), a specific resource ('custom MCP webhook'), and the expected outcome ('return delivery result'). This clearly distinguishes it from sibling webhook tools that create, update, delete, or list webhooks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The use case is implied: test a custom webhook's delivery. The safe-mode confirmation instruction adds concrete invocation guidance, but there is no explicit when-to-use vs alternatives such as inspecting a webhook with wp_get_custom_webhook or reviewing past deliveries with wp_list_webhook_deliveries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update ACF field values on a post/page (creates snapshot before update)
| Name | Required | Description | Default |
|---|---|---|---|
| fields | Yes | ACF field key/value pairs to update | |
| post_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral disclosure burden. It does disclose one genuine behavioral trait — '(creates snapshot before update)' — which implies rollback capability and signals the update is material. However, it omits other important behaviors for a mutation tool: whether the update merges with or replaces existing ACF values, how nested/repeater fields are handled, and whether validation failures are surfaced. One useful disclosure among several needed merits a 3.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with the primary action front-loaded and the secondary behavioral note (snapshot) efficiently appended in parentheses. Zero wasted words; the structure prioritizes the most decision-relevant information first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This tool is genuinely complex: it accepts a nested arbitrary object (fields with additionalProperties: {}), is a mutation, and has no output schema. The description does not explain how to structure the fields object, whether partial field sets are merged or treated as a full replacement (high-risk if an agent assumes replace semantics and wipes existing ACF data), or what the tool returns. For a mutation of this complexity, the one-line description leaves too much to inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% — 'fields' is described as 'ACF field key/value pairs to update' in the schema, but post_id has no schema description. The tool description adds marginal context by clarifying the target ('on a post/page'), which helps interpret post_id, but it does not explain the semantics of the fields object keys (field name vs. field key vs. field slug), which is a real ACF ambiguity. The description partially compensates for the 50% coverage gap but stops short of defining the nested object's format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update ACF field values on a post/page' uses a specific verb and resource, clearly identifying this as the ACF-field-level mutation tool. It distinguishes itself from the 120+ siblings, notably wp_update_post/wp_update_page (standard post data), wp_get_acf_fields (read counterpart), and wp_update_settings (site settings). The parenthetical '(creates snapshot before update)' adds a distinguishing behavioral feature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. With a large sibling set containing wp_get_acf_fields (read ACF values) and generic post/page updaters, the description provides no explicit routing, exclusions, or preconditions such as 'use wp_get_acf_fields first to read existing values' or 'use wp_update_post for standard post fields.' The usage context is only implied by the tool name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update Gutenberg block attributes by path or by finding block_name with optional match_text
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Block path from wp_list_blocks (e.g. 0.1.2) | |
| attrs | Yes | Block attributes to merge | |
| page_id | Yes | ||
| block_name | No | Block name to find when path is omitted | |
| match_text | No | Text to match when finding by block_name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It does disclose the genuine dual-mode locating behavior (path-based vs name-based lookup with optional text disambiguation), which goes beyond the schema. However, it omits important edge-case behavior: what happens when multiple blocks match block_name/match_text, what happens when no block is found, and whether path and block_name are mutually exclusive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence front-loads the verb and resource before the targeting details; there is no filler. The phrasing 'by finding block_name with optional match_text' is slightly awkward (it reads as if block_name itself is being found), but it remains compact and information-rich.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutating tool with 5 parameters, two targeting modes, no annotations, and no output schema, yet the definition stops at the core action. Missing context includes match-count behavior, error conditions for unfound blocks, whether path and block_name can be combined, and any pointer that wp_list_blocks is the prerequisite for obtaining a valid path.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80%, so the baseline is 3; the description adds marginal value by framing the relationship between path, block_name, and match_text as a coherent targeting strategy, though the schema already states 'when path is omitted' and 'when finding by block_name.' Notably, page_id — a required parameter — is undocumented in both the schema and the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Update') and a specific resource ('Gutenberg block attributes'), then immediately distinguishes the two targeting strategies: by path or by block_name with optional match_text. Among the sibling tools, only this one targets Gutenberg blocks specifically, differentiating it clearly from wp_update_post, wp_update_page, and the wp_elementor_update_* family.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description embeds a within-tool targeting rule (use path or use block_name/match_text) but gives no guidance about when to choose this tool over alternatives, such as wp_update_post for post fields or wp_elementor_update_element for Elementor pages. No prerequisites, exclusions, or sibling comparisons are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a WordPress category
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| name | No | ||
| slug | No | ||
| parent | No | ||
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full burden for behavioral transparency. It does not disclose any side effects, required permissions, or limitations of the update operation. It merely states the action without transparency into what changes are allowed or consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise, but it lacks structure and additional helpful details. While there is no wasted text, the brevity comes at the cost of completeness, making it borderline under-specified for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, no annotations, no output schema, and low schema description coverage, the description provides insufficient information for an agent to correctly use the tool. It fails to enumerate updatable fields, required parameters beyond 'id', or expected return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 5 properties (id, name, slug, description, parent) with 0% schema description coverage. The description adds no parameter-level meaning, leaving the agent to guess at valid values or constraints for each field. For example, it does not mention that 'slug' must be unique or that 'parent' refers to an existing category ID.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and the resource 'a WordPress category', so the main purpose is clear. However, it lacks specificity about which attributes can be updated, and it does not differentiate from siblings like wp_create_category or wp_delete_category.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. For example, it does not indicate that wp_create_category should be used for new categories, or that wp_list_categories is for retrieval. The description provides no context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing custom post type item (creates snapshot before update)
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| meta | No | ||
| slug | No | ||
| title | No | ||
| parent | No | ||
| status | No | ||
| content | No | ||
| excerpt | No | ||
| post_type | Yes | ||
| featured_media | No | ||
| scheduled_date | No | ISO or parseable date string to schedule publication |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It does disclose a significant behavior—creating a snapshot before the update—which implies recoverability. However, it does not mention permission requirements, whether unspecified fields are overwritten, or how partial updates are handled, leaving important behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler. It efficiently conveys the core action and the notable snapshot behavior. It could include more useful detail, but what is present is well structured and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 11 parameters, no output schema, and no annotations, the description is too sparse for an agent to invoke it correctly in varied contexts. It omits required parameter explanation, expected return behavior, and guidance on how meta/status/scheduled_date interact. The snapshot note is helpful but leaves many practical questions unanswered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 9% (only scheduled_date has a description), and the description adds no parameter-specific information. It does not explain that post_type and id are required, nor what each updatable field accepts. The schema provides types but lacks meaning, and the description fails to compensate for this low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'Update' and the resource 'existing custom post type item', which differentiates it from create/delete/get/list CPT item siblings. The parenthetical 'creates snapshot before update' adds a distinguishing feature. It lacks explicit contrast with the generic wp_update_post tool, but the resource specification is enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like wp_update_post or wp_get_cpt_item. The snapshot mention hints at a safety property but does not state when this tool should be preferred or when another update tool is more appropriate. An agent has to infer usage from the name and siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a custom MCP webhook (name, url, topics, enabled)
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Webhook ID | |
| url | No | ||
| name | No | ||
| topics | No | ||
| enabled | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and only says the named fields can be updated. It does not disclose whether the update is partial or full, whether omitted fields are reset, what permissions are needed, or what response is returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence that wastes no words and places the verb and resource first. It is appropriately compact, though it could add one clause about update semantics without becoming bloated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a five-parameter mutation tool with no annotations and no output schema, this is not enough. An agent is missing update semantics, prerequisite information, and any detail on topics/enabled behavior needed for a safe call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20%, and the description merely repeats the field names from the schema without adding substantive meaning. It does not explain topics semantics, the effect of enabled=false, or how missing optional fields are handled.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Update') and resource ('custom MCP webhook'), and lists the affected fields (name, url, topics, enabled). It clearly communicates the operation, though it does not explicitly contrast with sibling webhook-update tools such as update_form_webhook or update_woocommerce_webhook.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to update versus create/delete/test a custom webhook, or whether the webhook must already exist. The intended context must be inferred entirely from the tool name and sibling set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update Ninja Form notification actions (email recipients, subject, message, etc.)
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Form ID | |
| actions | Yes | Notification action updates keyed by action ID or settings |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not state whether this operation replaces all notification actions, merges updates, requires permissions, is reversible, or what response shape to expect. The word 'update' indicates mutation but leaves significant behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It immediately states the operation, resource, and representative fields, making it easy to scan and process.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an update operation with no annotations and no output schema, the description is thin. It does not explain how the actions array maps to notification action IDs, whether updates are incremental or destructive, or what the caller should expect as a successful result. An agent would need more guidance to invoke this tool confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters adequately. The description adds domain-specific examples like 'email recipients, subject, message,' which clarifies what the actions array might contain, but it does not explain the structure of the actions items or how updates are keyed beyond what the schema already says.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' plus a specific resource: 'Ninja Form notification actions.' The parenthetical examples (email recipients, subject, message) further clarify the domain, and this clearly differentiates it from sibling tools like wp_update_form_webhook or generic form tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used when updating notification actions for a Ninja Form, but it does not explicitly provide when-to-use/when-not-to-use guidance or name alternatives. There are no direct siblings competing for the same action, so the implied usage is acceptable but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a Ninja Forms webhook action
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | ||
| label | No | ||
| active | No | ||
| method | No | ||
| form_id | Yes | Ninja Form ID | |
| headers | No | ||
| action_id | Yes | Webhook action ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only repeats the mutation implied by the name and does not explain effects on existing webhook actions, whether unspecified fields are preserved or overwritten, or what response to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no filler or redundant phrasing. It is front-loaded with the action verb, though the brevity sacrifices useful detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters, 29% schema coverage, no output schema, and no annotations, a one-line description is far from complete. The agent lacks information about required identifiers, optional update fields, nested header structure, and return behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 29%, and the description names none of the parameters. It does not clarify the meaning or usage of url, label, active, method, headers, form_id, or action_id beyond what the sparse schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Update') and resource ('Ninja Forms webhook action'), so the core purpose is understandable. However, it does not explicitly differentiate from sibling tools like wp_create_form_webhook or wp_delete_form_webhook beyond the verb itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, no prerequisites, and no context about existing webhook actions. The agent is left to infer usage solely from the word 'Update'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update media title, alt text, caption, or description
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| alt | No | ||
| title | No | ||
| caption | No | ||
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only says 'update' which implies mutation, but says nothing about whether the operation is atomic, whether it overwrites or merges, error handling, return values, or required permissions. This is minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the purpose. Every word is relevant, no redundancy or verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters, no output schema, and no annotations, the description is too sparse. It does not explain that the id must correspond to an existing media item, what the response looks like, whether all parameters are optional beyond id, or any side effects. Lacks essential context for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should add meaning beyond parameter names. It merely lists the same field names (title, alt, caption, description) as in the schema, without explaining formats, constraints (e.g., max length), or how they map to WordPress media fields. Adds almost no value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and the resource 'media metadata', listing the specific fields it affects (title, alt text, caption, description). It distinguishes from siblings like wp_update_post or wp_update_page which update different content types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for updating media metadata but does not provide explicit guidance on when to use this tool versus alternatives like wp_update_post for post attachments or wp_upload_media for creation. No when-not or alternative tooling is mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update WooCommerce order status, addresses, or line items. confirm:true required when safe mode is enabled.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| status | No | ||
| billing | No | ||
| confirm | No | Required when safe mode is enabled | |
| shipping | No | ||
| line_items | No | ||
| customer_note | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose a meaningful gate — safe mode demands explicit confirm:true — which signals that the operation is mutating and confirmation-controlled. But it does not say whether updates merge or replace existing data (especially for billing/shipping), what side effects occur (totals recalculation, order emails, webhooks), or what the operation returns.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Fourteen words across two sentences: purpose first, constraint second. There is zero filler and no restating of schema types. Every clause earns its place, and the safe-mode caveat is positioned exactly where the reader decides whether to call the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter tool with nested objects, no annotations, and no output schema, this is minimal but viable: the required id is schema-enforced, the updateable areas are named, and the safe-mode confirm gate is flagged. Clear gaps remain — whether updates are partial/merge or full/replace, whether confirm can be omitted when safe mode is off, and the response shape — making it adequate rather than complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 14% (only confirm has a schema-level description), so the tool description must compensate. It maps three parameter groups to their real-world meaning (status, addresses, line items), which helps. However, it adds nothing about customer_note, does not explain the shape of the billing/shipping string maps, and largely restates the confirm requirement that the schema already documents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb, resource, and scope: 'Update WooCommerce order status, addresses, or line items.' This differentiates it from read siblings like wp_get_order/wp_list_orders and from related mutations like wp_refund_order or wp_add_order_note. It loses a point because the 'or' phrasing implies the update targets are mutually exclusive when they are combinable, and it omits customer_note, which the schema explicitly supports.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides one concrete conditional rule: 'confirm:true required when safe mode is enabled,' which tells the agent when a prerequisite applies. However, it never states when to choose this tool over alternatives such as wp_add_order_note (notes) or wp_refund_order (refunds), nor does it give exclusions. Usage context is mostly implied by the tool name and the update target rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing WordPress page (creates snapshot before update)
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Page ID | |
| meta | No | ||
| slug | No | ||
| title | No | ||
| parent | No | ||
| status | No | ||
| content | No | ||
| excerpt | No | ||
| template | No | ||
| featured_media | No | ||
| scheduled_date | No | ISO or parseable date string to schedule publication |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden; it does disclose the valuable fact that a snapshot is created before each update, implying the operation is recoverable. However, it does not disclose how unspecified fields or the nested meta object are handled (merge vs. overwrite), whether the change is revertible via wp_restore_snapshot, or any permission/error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with the action first and the key safety behavior in a parenthetical. Every word earns its place; there is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating tool with 11 parameters, a nested object, no annotations, and no output schema, this description is thin. An agent cannot tell what the response looks like, whether fields omitted from the request are preserved or reset, or how to leverage the snapshot for rollback despite related tools like wp_restore_snapshot and wp_get_snapshot_diff existing in the sibling set.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low at 18% (only id and scheduled_date described), yet the description adds no parameter-level meaning. In particular, the nested meta object's merge/replace semantics are left undefined, and fields like status, template, and featured_media are left to the agent's inference.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Update') and a specific resource ('existing WordPress page'), with a useful behavioral note about snapshots. The word 'existing' distinguishes it from wp_create_page and 'page' separates it from wp_update_post, though this differentiation relies partly on the tool name rather than explicit sibling routing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to prefer this tool over alternatives such as wp_create_page or wp_update_post. The word 'existing' weakly implies it is for already-created pages, but no when-to-use conditions, exclusions, or named alternatives are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update SEO fields for a page/post via All in One SEO (creates snapshot before update)
| Name | Required | Description | Default |
|---|---|---|---|
| fields | Yes | SEO field key/value pairs — use wp_get_page_seo catalog for allowed keys | |
| page_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses the important side effect of creating a snapshot before updating, which hints at recoverability. It does not address whether fields are merged or replaced, permissions required, or what a successful update returns.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence states the action, scope, plugin, and safety side effect with no filler. Every word contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity two-parameter tool, the definition plus schema covers how to choose fields and what resource is being updated. It is still incomplete for a mutating tool with no annotations and no output schema, because it does not describe the response format, merge vs. replace semantics, or how to use the created snapshot for rollback.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema adequately documents the 'fields' parameter and directs agents to the wp_get_page_seo catalog for allowed keys. The tool description additionally clarifies that the target is a page or post, which is crucial semantics for the otherwise undocumented page_id parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the exact operation ('Update SEO fields') and resource ('a page/post via All in One SEO'), clearly distinguishing it from generic wp_update_page and read-only wp_get_page_seo. It also adds a notable side effect ('creates snapshot before update') that helps differentiate it from similar update tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied: an agent should call this when updating All in One SEO fields for a page or post. However, it does not explicitly state when to prefer this over wp_update_page, and it relies on the schema parameter description to point the agent to wp_get_page_seo for allowed field keys.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing WordPress post (creates snapshot before update)
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| meta | No | ||
| slug | No | ||
| tags | No | ||
| title | No | ||
| status | No | ||
| sticky | No | ||
| content | No | ||
| excerpt | No | ||
| categories | No | ||
| featured_media | No | ||
| scheduled_date | No | ISO or parseable date string to schedule publication |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose one meaningful side effect—'creates snapshot before update'—which hints at reversibility. However, it omits other important behavioral details such as whether updates are partial or full replacements, permission requirements, or effects on related data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. The core action is stated first, and the snapshot side effect is neatly contained in parentheses. This structure is both concise and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a 12-parameter mutation tool with no annotations and no output schema, yet the description gives almost no operational context. It does not explain how to perform partial updates, what happens to omitted fields, whether meta/categories/tags replace or merge, or what the agent should expect in the response. The snapshot note is helpful but far from sufficient for such a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 8%, so the description must compensate by explaining parameter semantics, but it does not mention any parameters. For instance, it does not clarify whether meta, categories, and tags replace or merge with existing values, or what the scheduled_date format expectations are beyond the schema's brief note.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Update an existing WordPress post.' It clearly distinguishes this from sibling tools like wp_create_post, wp_delete_post, and wp_update_page by naming the exact object type (post) and implying an existing resource. The parenthetical about snapshots adds useful context without confusing the core purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when updating an existing WordPress post) but provides no explicit guidance about alternatives. It does not mention that pages use wp_update_page, or that creating a post should use wp_create_post, leaving the agent to infer routing from the resource name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a WooCommerce product (creates snapshot before update)
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| sku | No | ||
| name | No | ||
| slug | No | ||
| status | No | ||
| featured | No | ||
| sale_price | No | ||
| description | No | ||
| manage_stock | No | ||
| stock_status | No | ||
| regular_price | No | ||
| stock_quantity | No | ||
| short_description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose a meaningful side effect: a snapshot is created before the update, which implies recoverability. However, it omits other behavioral details relevant to a mutation tool, such as whether changes are reversible, required permissions, response behavior, or side effects beyond the snapshot.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded, but it is under-specified rather than appropriately concise for a tool with 13 parameters and no schema descriptions or output schema. A single clause cannot carry the necessary information for correct usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 13 parameters, 0% schema description coverage, no annotations, and no output schema, the description is far from complete. It identifies the operation and snapshot behavior but leaves parameter usage, alternative routing, output expectations, and prerequisites undocumented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no meaning for any of the 13 parameters. It does not even note that 'id' is required or explain how fields like sale_price, stock_status, or manage_stock relate to the update. The agent must guess parameter semantics from bare type names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update a WooCommerce product') and adds a distinguishing safety note about creating a snapshot before updating. It identifies the general resource and operation, but it does not explicitly distinguish itself from the sibling wp_update_product_price or clarify whether price updates belong here or there.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus alternatives such as wp_create_product, wp_update_product_price, or wp_delete_product. The snapshot note hints at a safety-oriented workflow, but it does not state when this tool should be chosen over related product tools or mention any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update WooCommerce product pricing (regular_price, sale_price, or price alias)
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| price | No | Alias for regular_price | |
| sale_price | No | ||
| regular_price | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description is responsible for disclosing behavior. It only says 'update' and lists fields, but does not explain whether unspecified price fields are preserved, what happens when both sale_price and regular_price are provided, how to clear a price, or any side effects. For a mutation tool this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler and places the verb/resource first. It earns its place, though it sacrifices behavioral detail for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation with 4 parameters and no output schema, the description is under-specified. It does not explain return behavior, required product existence, or interactions between price fields, and the low schema coverage means an agent has little to work with. The bare listing of fields is the minimum viable information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only the schema's 'price' parameter has a description ('Alias for regular_price'); regular_price and sale_price are otherwise undocumented in both schema and description. The description merely re-lists parameter names and does not clarify accepted string formats, currency handling, or precedence when multiple fields are passed. With 25% schema coverage, the description should compensate but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Update'), a resource ('WooCommerce product pricing'), and names exactly which fields are involved (regular_price, sale_price, price alias). This clearly separates it from the broader wp_update_product sibling, making the tool's scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to choose this tool over wp_update_product or other product-related tools. There is no 'when to use' or 'when not to use' statement, so an agent would have to infer from the name/description alone. This is a clear gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing redirect
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| enabled | No | ||
| target_url | No | ||
| source_path | No | ||
| status_code | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any behavioral traits such as whether updates are partial or full, what happens to omitted fields, or any side effects like immediate propagation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (4 words) but lacks necessary detail; it is underspecified and does not earn its brevity by being self-explanatory.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, no annotations, and 0% parameter documentation, the description fails to adequately inform an agent about the tool's full behavior and requirements.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no meaning to any of the 5 parameters (id, source_path, target_url, status_code, enabled). An agent must rely solely on parameter names, which may be insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Update') and resource ('an existing redirect'), distinguishing it from sibling tools like wp_create_redirect, wp_delete_redirect, and wp_list_redirects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., create or delete), nor any prerequisites or context for updating a redirect.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update safe WordPress site settings (title, tagline, posts per page, front page)
| Name | Required | Description | Default |
|---|---|---|---|
| blogname | No | Site title | |
| page_on_front | No | ||
| show_on_front | No | ||
| page_for_posts | No | ||
| posts_per_page | No | ||
| blogdescription | No | Site tagline |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states 'Update safe' which hints at non-destructive behavior, but it does not disclose other behavioral traits such as whether changes take effect immediately, validation errors, or side effects. A mutation tool should provide more transparency about its impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that effectively communicates the tool's purpose. It is front-loaded with the primary verb and resource. However, it could include a bit more detail on parameter usage without becoming overly verbose, hence slightly above average.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters, no annotations, no output schema, and low schema description coverage, the description is insufficiently complete. It does not explain how to set the front page (requires combining show_on_front and page_on_front), or handle optional parameters. An agent lacks critical context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds some value by mapping 'title' to blogname, 'tagline' to blogdescription, etc., covering 4 of the 6 parameters. However, schema description coverage is only 33%, and the description does not explain the remaining parameters (show_on_front, page_on_front) or their interplay. It partially compensates for the schema gap but is not comprehensive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update safe WordPress site settings' and lists specific settings (title, tagline, posts per page, front page), making the tool's purpose very clear. It distinguishes from sibling tools like wp_get_settings (read) and other update tools (e.g., wp_update_post), so an agent can easily identify it as the correct tool for site-level setting updates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for updating site-level settings but does not explicitly state when to use this tool versus alternatives. It lacks guidance on when not to use it (e.g., for post-level settings) or any prerequisites. However, the context of sibling tools provides some implicit differentiation, so the score is adequate but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a WordPress tag
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| name | No | ||
| slug | No | ||
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral transparency. It only states 'Update', which is already clear from the name, but fails to disclose any side effects, permission requirements, or idempotency properties. For a mutation tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at four words, which is efficient but under-specified. It could include additional context, such as a brief note about the optional parameters, without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and no parameter descriptions, the tool description is severely incomplete. An agent needs to know the effects of each parameter, any constraints (e.g., unique slug), and the return value to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 4 parameters with 0% description coverage (no descriptions in schema). The tool description adds no information about what each parameter does, such as the meaning of 'slug' or 'description' for a tag. This leaves the agent to infer semantics from parameter names alone, which is inadequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update a WordPress tag' clearly states the action (update) and the resource (tag), distinguishing it from sibling tools like wp_create_tag and wp_delete_tag. However, it does not elaborate on the specific attributes that can be updated, which the input schema partially covers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. For example, it does not mention that wp_create_tag should be used for new tags or that the tag must exist before updating. The usage context is entirely implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a text or custom_html widget instance by widget ID
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Widget instance ID (e.g. text-2, custom_html-3) | |
| text | No | Content for text widgets | |
| title | No | ||
| content | No | HTML content for custom_html widgets |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden of behavioral disclosure. It only says 'Update' and does not explain whether this is a partial or full overwrite, what happens when title/text/content are omitted, or what response is returned. This is a significant gap for a mutating tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one concise sentence with the operation, target resource, type restriction, and identifier method front-loaded. There is no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is too thin. It leaves important invocation details unspecified, such as overwrite behavior, whether omitted fields are preserved or cleared, and what success/failure looks like. The schema covers parameter names but not the behavioral context an agent needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents id, text, and content (75% coverage), so the description adds only modest context by tying the tool to 'text or custom_html' widget types. It does not clarify the undocumented 'title' parameter or whether text and content are mutually exclusive based on widget type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the operation ('Update'), the resource ('widget instance'), and narrows it to 'text or custom_html' types with 'by widget ID'. This clearly differentiates it from sibling update tools such as wp_update_page and wp_update_post, which target different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended usage is implied: use this tool to update text or custom_html widget instances, and the 'by widget ID' phrase signals a prerequisite. However, it does not explicitly state when to prefer this tool over alternatives or when not to use it, leaving the guidance implicit rather than direct.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a WooCommerce native webhook
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | WooCommerce webhook ID | |
| name | No | ||
| topic | No | ||
| status | No | ||
| delivery_url | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits on its own, but it only says 'Update'. It does not explain whether updates are partial or full, what side effects might occur, whether permissions are required, or what the response contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It effectively names the operation and resource, though its brevity borders on under-specification rather than being a model of concise completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with five parameters, no annotations, and no output schema, this one-line description is severely incomplete. It omits all parameter semantics, side effects, return values, and usage context, leaving the agent without enough information to invoke the tool reliably.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20% (id), and the description adds no meaning for name, topic, status, or delivery_url. It fails to compensate for the four undocumented parameters, leaving the enum on status and the uri format on delivery_url as the only semantic hints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Update') and a specific resource ('WooCommerce native webhook'), and 'native' helps distinguish it from custom webhook tools. However, it does not explicitly contrast with sibling tools like wp_update_custom_webhook or wp_update_form_webhook, so it falls short of full differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool instead of wp_create_woocommerce_webhook, wp_update_custom_webhook, or wp_update_form_webhook. It also omits prerequisites, constraints, and exclusions, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload media to WordPress from base64-encoded data
| Name | Required | Description | Default |
|---|---|---|---|
| alt | No | ||
| data | Yes | Base64-encoded file data | |
| title | No | ||
| caption | No | ||
| filename | No | upload.jpg | |
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It only states the basic function and fails to mention error handling, file size limits, supported MIME types, overwriting behavior, or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise, but it lacks necessary details. It is appropriately front-loaded but under-specified, making it minimally adequate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, no output schema), the description is incomplete. It does not explain return values, error conditions, or behavioral aspects. Sibling tools exist but are not compared or contrasted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 17% (only 'data' has a description). The tool description does not add meaning beyond the schema, especially for undocumented parameters like title, alt, caption, and description. It fails to compensate for the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Upload', the resource 'media to WordPress', and the input method 'from base64-encoded data'. It effectively distinguishes from siblings like wp_upload_media_from_url by specifying the encoding format.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no prerequisites, no exclusions, and no context for appropriate usage. The agent receives no help in deciding between this and similar upload tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload media to WordPress from a remote URL
| Name | Required | Description | Default |
|---|---|---|---|
| alt | No | Alt text for images | |
| url | Yes | Image or file URL to upload | |
| title | No | ||
| caption | No | ||
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden. It only states the basic action without disclosing side effects, permission requirements (e.g., upload_files capability), file type/ size limits, error handling, or return behavior. This is insufficient for an upload tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no unnecessary words, effectively communicating the core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, no output schema, and no annotations, the description is too minimal. It does not explain return values (e.g., media ID), error scenarios, or usage prerequisites, making it incomplete for reliable agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 5 parameters but only 2 have descriptions (url and alt). Schema description coverage is 40%, and the tool description adds no extra meaning beyond what the schema already provides. Parameters like title, caption, and description lack any explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'upload', the resource 'media', and the source 'from a remote URL'. It is specific and distinguishes from the sibling tool wp_upload_media_from_base64.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for uploading media from a remote URL, which is clear context. However, it does not explicitly mention alternatives or when not to use it, but the name and description suffice for basic guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v2.3.0wp_activate_pluginwp_add_order_notewp_audit_seowp_create_cpt_itemwp_create_custom_webhookwp_create_form_webhookwp_create_page1 field changedInput schema / properties / scheduled_dateAdded value: +{
+ "description": "ISO or parseable date string to schedule publication",
+ "type": "string"
+}wp_create_post1 field changedInput schema / properties / scheduled_dateAdded value: +{
+ "description": "ISO or parseable date string to schedule publication",
+ "type": "string"
+}wp_create_productwp_create_taxonomy_termwp_create_userwp_create_woocommerce_webhookwp_deactivate_pluginwp_delete_cpt_itemwp_delete_custom_webhookwp_delete_form_webhookwp_delete_productwp_delete_woocommerce_webhookwp_elementor_add_repeater_itemwp_elementor_clear_pagewp_elementor_create_blank_pagewp_elementor_find_parentwp_elementor_get_template_conditionswp_elementor_list_repeater_itemswp_elementor_list_theme_templateswp_elementor_publish_templatewp_elementor_regenerate_csswp_elementor_remove_repeater_itemwp_elementor_repair_jsonwp_elementor_set_template_conditionswp_elementor_update_repeater_itemwp_get_acf_fieldswp_get_bookingwp_get_cpt_itemwp_get_custom_webhookwp_get_formwp_get_meta_catalogwp_get_orderwp_get_page_seowp_get_plugin_conflictswp_get_plugin_updateswp_get_productwp_get_revisionwp_get_revision_diffwp_get_site_blueprintwp_get_snapshot_diffwp_get_userwp_get_woocommerce_webhookwp_insert_block_patternwp_list_blockswp_list_booking_productswp_list_commentswp_list_cpt_itemswp_list_cron_eventswp_list_custom_webhookswp_list_form_submissionswp_list_form_webhookswp_list_formswp_list_orderswp_list_post_typeswp_list_productswp_list_revisionswp_list_roleswp_list_sidebarswp_list_taxonomieswp_list_taxonomy_termswp_list_userswp_list_webhook_deliverieswp_list_webhook_topicswp_list_widget_instanceswp_list_woocommerce_webhookswp_moderate_commentwp_purge_cachewp_refund_orderwp_reply_to_commentwp_restore_revisionwp_security_posturewp_site_auditwp_test_custom_webhookwp_update_acf_fieldswp_update_blockwp_update_cpt_itemwp_update_custom_webhookwp_update_form_notificationswp_update_form_webhookwp_update_orderwp_update_page1 field changedInput schema / properties / scheduled_dateAdded value: +{
+ "description": "ISO or parseable date string to schedule publication",
+ "type": "string"
+}wp_update_page_seowp_update_post1 field changedInput schema / properties / scheduled_dateAdded value: +{
+ "description": "ISO or parseable date string to schedule publication",
+ "type": "string"
+}wp_update_productwp_update_product_pricewp_update_widget_instancewp_update_woocommerce_webhookv1.0.0wp_assign_menu_locationwp_batch_operationswp_create_categorywp_create_landing_pagewp_create_menu_itemwp_create_pagewp_create_postwp_create_redirectwp_create_tagwp_delete_categorywp_delete_mediawp_delete_menu_itemwp_delete_pagewp_delete_postwp_delete_redirectwp_delete_tagwp_elementor_clone_elementwp_elementor_duplicate_pagewp_elementor_find_widgetswp_elementor_get_structurewp_elementor_get_widget_catalogwp_elementor_insert_sectionwp_elementor_insert_widgetwp_elementor_list_elementswp_elementor_remove_elementwp_elementor_update_buttonwp_elementor_update_elementwp_elementor_update_imagewp_elementor_update_textwp_export_site_structurewp_generate_sitemapwp_get_activity_logwp_get_mediawp_get_menu_itemswp_get_pagewp_get_postwp_get_settingswp_get_site_infowp_health_checkwp_list_categorieswp_list_mediawp_list_menuswp_list_pageswp_list_pluginswp_list_postswp_list_redirectswp_list_tagswp_list_themeswp_restore_snapshotwp_search_contentwp_update_categorywp_update_media_metadatawp_update_menu_itemwp_update_pagewp_update_postwp_update_redirectwp_update_settingswp_update_tagwp_upload_media_from_base64wp_upload_media_from_urlMany tools are clearly separated by resource type, but there are notable overlaps: wp_elementor_update_element is a general tool that subsumes wp_elementor_update_text/button/image, and wp_update_product overlaps with wp_update_product_price. Similarly, the line between generic CPT tools and concrete post/page/product tools can be blurry. Overall, descriptions help but the large surface creates real selection ambiguity.
Every tool follows the same wp_verb_noun snake_case pattern. List/get/create/update/delete are used predictably across all resource types, and specialized actions like restore, clone, purge, and audit also follow the convention consistently. No mixed casing or random verb styles are present.
With 149 tools, this is an extreme count that goes well beyond what an agent can efficiently navigate or reliably select from. Even a broad WordPress control surface does not justify this many individual operations, and the count strongly harms coherence and usability.
The surface is exceptionally broad: posts, pages, media, users, comments, taxonomies, menus, plugins, themes, settings, SEO, Elementor, WooCommerce, forms, webhooks, redirects, snapshots, revisions, and audits are all covered. Minor gaps exist—such as no user update/delete, no menu create/update/delete, and no form submission get/delete—but they do not block most workflows.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
WordPress MCP server: publish posts, AI images, SEO and full site management, self-hosted
Security-first WordPress MCP server. 129 tools for Claude, ChatGPT, Gemini. Free on wp.org.
WordPress MCP server: generate SEO posts, AI images, autoblog & WooCommerce on your self-hosted site
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/mpierre135/wp-mcp-control-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
