An MCP (Model Context Protocol) server that gives AI assistants direct access to WP HealthKit's plugin audit API. Once configured, tools like Claude Desktop, Claude Code, and Cursor can trigger security audits, retrieve findings, fetch AI-ready fix prompts, bulk-audit entire plugin directories, and flag false positives — all without leaving the chat interface.
WPHK_API_KEY=your_api_key_hereGet your API key from wphealthkit.com/dashboard.
Add the following to your claude_desktop_config.json (usually at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"wphealthkit": {
"command": "npx",
"args": ["-y", "@wphealthkit/mcp-server"],
"env": {
"WPHK_API_KEY": "your_api_key_here"
}
}
}
}Add to your project's .mcp.json:
{
"mcpServers": {
"wphealthkit": {
"command": "npx",
"args": ["-y", "@wphealthkit/mcp-server"],
"env": {
"WPHK_API_KEY": "your_api_key_here"
}
}
}
}Open Cursor Settings > MCP > Add Server and use:
{
"wphealthkit": {
"command": "npx",
"args": ["-y", "@wphealthkit/mcp-server"],
"env": {
"WPHK_API_KEY": "your_api_key_here"
}
}
}Related MCP server: VibeCheck MCP Server
Tool | Description |
| Trigger a security audit for a wp.org plugin by slug. Returns an audit ID. |
| Trigger an audit from a local ZIP file. Returns an audit ID. |
| Audit all plugin ZIP files in a local directory. Submits in batches of 10, streams results as each completes, and prints a final summary with risk breakdown and links to top findings. |
| Poll the status and full results of an audit by its ID. |
| Get paginated findings, with optional filters for severity and category. |
| Get AI-ready fix prompts for an audit's findings, batched by severity. |
| Look up a plugin's security grade, risk level, and findings count from the directory. |
| Check your current usage — audits used this month, tier, and limits. |
| Flag a finding as a false positive. The report goes to the WP HealthKit team for review; confirmed patterns result in a scanner rule update that prevents that pattern in all future audits. |
audit_pluginTriggers a security audit for any plugin hosted on wp.org.
Parameters
Parameter | Type | Required | Description |
|
| Yes | The wp.org plugin slug (e.g. |
|
| No | Audit engines to run. Defaults to all engines. |
Example
audit_plugin({ slug: "contact-form-7" })
// Returns: { auditId: "abc-123", status: "queued" }audit_plugin_zipTriggers an audit from a local ZIP file. Useful for plugins not on wp.org or pre-release builds.
Parameters
Parameter | Type | Required | Description |
|
| Yes | Absolute path to the ZIP file on disk. |
|
| No | Audit engines to run. Defaults to all engines. |
Example
audit_plugin_zip({ path: "/Users/me/plugins/my-plugin.zip" })
// Returns: { auditId: "def-456", status: "queued" }audit_plugins_bulkAudits all plugin ZIP files in a local directory. Submissions are batched in groups of 10. Results stream as each audit completes, and a final summary table is printed with a risk breakdown and links to top findings.
Parameters
Parameter | Type | Required | Description |
|
| Yes | Absolute path to the directory containing plugin ZIPs. |
|
| No | Audit engines to run (e.g. |
|
| No | Glob pattern to match files. Defaults to |
Example
audit_plugins_bulk({ directory: "/Users/me/plugins", engines: [] })Output
Results stream to the conversation as each plugin completes. Once all audits finish, the tool prints a summary table:
Plugin Risk Findings Report
---------------------- -------- --------- ----------------------------------------
my-plugin.zip CRITICAL 14 https://wphealthkit.com/report/abc-123
another-plugin.zip LOW 2 https://wphealthkit.com/report/def-456
legacy-plugin.zip HIGH 7 https://wphealthkit.com/report/ghi-789
Summary: 3 plugins audited — 1 CRITICAL, 1 HIGH, 0 MEDIUM, 1 LOWget_reportPolls the status and full results of an audit. Call this after audit_plugin or audit_plugin_zip to wait for completion and retrieve the report.
Parameters
Parameter | Type | Required | Description |
|
| Yes | The audit ID returned by |
Example
get_report({ auditId: "abc-123" })
// Returns: { status: "completed", grade: "C", riskLevel: "HIGH", findingsCount: 7, reportUrl: "..." }get_findingsReturns paginated findings for a completed audit. Supports filtering by severity and category.
Parameters
Parameter | Type | Required | Description |
|
| Yes | The audit ID. |
|
| No | Filter by severity: |
|
| No | Filter by category (e.g. |
|
| No | Page number for pagination. Defaults to |
Example
get_findings({ auditId: "abc-123", severity: "CRITICAL" })get_fix_promptReturns AI-ready fix prompts for an audit's findings, grouped and batched by severity. Pass the output directly to a coding assistant to generate patches.
Parameters
Parameter | Type | Required | Description |
|
| Yes | The audit ID. |
|
| No | Limit prompts to a specific severity level. |
Example
get_fix_prompt({ auditId: "abc-123", severity: "HIGH" })check_pluginLooks up a plugin's current security grade, risk level, and findings count from the WP HealthKit directory without triggering a new audit.
Parameters
Parameter | Type | Required | Description |
|
| Yes | The wp.org plugin slug. |
Example
check_plugin({ slug: "woocommerce" })
// Returns: { grade: "B", riskLevel: "MEDIUM", findingsCount: 3, lastAudited: "2026-04-20" }list_usageReturns your current billing period usage — audits consumed, tier, and remaining quota.
Parameters
None.
Example
list_usage()
// Returns: { auditsUsed: 47, auditsLimit: 100, tier: "pro", resetsAt: "2026-05-01" }flag_findingFlags a finding as a false positive. The report is reviewed by the WP HealthKit team. If the pattern is confirmed as a false positive, the scanner rule is updated to prevent the same result from appearing in all future audits.
Parameters
Parameter | Type | Required | Description |
|
| Yes | UUID of the audit containing the finding. |
|
| Yes | ID of the finding to flag (e.g. |
|
| Yes | Title of the finding as shown in the report. |
|
| No | Explanation of why this is a false positive. |
Example
flag_finding({
auditId: "abc-123-def-456",
findingId: "finding-5",
findingTitle: "Named arguments used in internal function call",
reason: "These are positional args — the scanner is misidentifying the call signature"
})
// Returns: { flagged: true, reviewTicket: "FP-2891" }audit_plugin({ slug: "my-plugin" })
→ get_report({ auditId: "..." }) // poll until status === "completed"
→ get_findings({ auditId: "...", severity: "CRITICAL" })
→ get_fix_prompt({ auditId: "..." })audit_plugins_bulk({ directory: "/Users/me/plugins" })
// streams per-plugin results as they complete
// prints final summary table with risk breakdowncheck_plugin({ slug: "advanced-custom-fields" })
// returns grade, risk level, and findings count without consuming an audit creditget_findings({ auditId: "...", severity: "HIGH" })
→ flag_finding({
auditId: "...",
findingId: "finding-12",
findingTitle: "Unescaped output in template",
reason: "Output is escaped upstream via wp_kses before reaching this call"
})Variable | Default | Description |
| — | Required. Your WP HealthKit API key. |
|
| Override to point at a self-hosted or staging instance. |
MIT
Trigger a security audit for a WordPress plugin by its wp.org slug. Optionally pass engines: ['performance'] for extended performance analysis (+1 token). Submits to the job queue and polls until complete (up to 20 minutes). Returns the full audit summary.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | The wp.org plugin slug (e.g. 'contact-form-7') | |
| engines | No | Optional extra engines. ['performance'] adds performance analysis (+1 token). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses the asynchronous nature ('Submits to the job queue and polls until complete'), the timeout ('up to 20 minutes'), the return value ('full audit summary'), and the token cost for extra engines. This is exemplary behavioral 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 three sentences, front-loaded with the core action, and uses compact phrases like '(+1 token)' to convey cost without 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?
The tool has no output schema, so the description's mention of returning the 'full audit summary' fulfills that gap. It also explains the job queue and timeout, making it sufficient for an agent to invoke and handle the tool's 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?
The schema already provides complete descriptions for both parameters (100% coverage). The description repeats the engines option but adds no new semantic meaning beyond what the schema contains, so a 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 'Trigger' and identifies the resource 'security audit' for a WordPress plugin, with the method 'by its wp.org slug'. This clearly distinguishes from siblings like audit_plugin_zip (which implies zip-based audits) and audit_plugins_bulk (which handles multiple 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?
The description clearly states the targeting mechanism ('by its wp.org slug') and the optional engine option, giving the agent enough context to know when to invoke this tool. However, it does not explicitly name alternatives or exclusions, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Audit all plugin ZIP files in a local directory. Submits in batches of 10 via the job queue, streams results as each audit completes, and prints a summary table. Useful for auditing an entire plugin suite at once.
| Name | Required | Description | Default |
|---|---|---|---|
| engines | No | Optional extra engines. ['performance'] adds performance analysis (+1 token per plugin). | |
| pattern | No | Extension filter in the form *.ext (default: '*.zip') | |
| directory | Yes | Absolute path to a folder containing plugin .zip files |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: 'Submits in batches of 10 via the job queue, streams results as each audit completes, and prints a summary table' gives concrete behavioral insights. It could add details like error handling or what happens to invalid files, but the core behavior is clearly 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 three sentences, each earning its place: purpose, behavioral details (batching/streaming/summary), and usage context. No fluff or redundancy. It is fully front-loaded with the main purpose 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?
Given the tool's complexity (bulk operation, batching, streaming) and lack of output schema, the description covers the essential behaviors and outcomes. It doesn't mention potential edge cases like empty directories or error reporting, but it is largely complete for an agent to understand what the tool does and when to use 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 parameter descriptions are already informative, so baseline is 3. The description adds no additional parameter semantics beyond what the schema provides; it only implies that engines affect analysis, which the schema already states. Thus, no extra value from 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 clearly states 'Audit all plugin ZIP files in a local directory', which is a specific verb+resource+scope. It distinguishes itself from sibling tools like audit_plugin and audit_plugin_zip by focusing on bulk auditing of all files in a directory, and the name 'bulk' reinforces this.
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 with 'Useful for auditing an entire plugin suite at once', indicating when to use the tool. However, it does not explicitly mention alternatives or when not to use it, such as for single plugin audits, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Audit a WordPress plugin from a local ZIP file. Provide the absolute or relative path to the .zip file. Submits to the job queue and polls until complete (up to 20 minutes). Returns the full audit summary.
| Name | Required | Description | Default |
|---|---|---|---|
| engines | No | Optional extra engines. ['performance'] adds server load, caching, and asset loading analysis (+1 token). | |
| file_path | Yes | Absolute or relative path to the plugin .zip file (e.g. './my-plugin.zip' or '/Users/me/plugins/my-plugin.zip') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses key behavioral details: asynchronous submission to a job queue, polling until completion, a 20-minute timeout, and the return of a full audit summary. This is valuable context, though it omits error handling and potential side effects like job record persistence.
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 concise sentences, each earning its place: purpose, usage instruction, and behavioral details. There is no redundancy or filler, making it easy to scan and 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?
Given the tool has only 2 parameters and no output schema, the description comprehensively covers what the tool does, how to invoke it, the asynchronous behavior, timeout, and return value. The distinction from sibling tools is also clear, making it complete for the agent to select and use 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% for both parameters, so the description adds little beyond what is already in the schema. It repeats the instruction to provide the path but does not elaborate on engines or file_path beyond the schema definitions. The baseline of 3 is appropriate since the schema handles 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 uses a specific verb 'Audit' with a well-defined resource 'WordPress plugin from a local ZIP file', clearly distinguishing it from sibling tools like audit_plugin (which likely audits a plugin by slug) and audit_plugins_bulk (which handles multiple plugins). It also states the required input (path to the zip), eliminating ambiguity.
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 this tool: when you have a local ZIP file to audit, and it instructs the user to provide the path. However, it does not explicitly mention alternatives or when not to use it (e.g., for remote plugins or bulk audits), so it lacks explicit exclusions but provides clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up a plugin's latest security grade, risk level, and findings count from the WP HealthKit directory.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | The wp.org plugin slug |
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 communicates a non-destructive read-only operation via 'look up', but it does not disclose data freshness, caching, network dependency, or error behavior. The verb provides some transparency, but more detail would be expected.
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 uses every word effectively. It focuses on the action and resource without any 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 simple one-parameter tool with no output schema, the description adequately lists the returned information (security grade, risk level, findings count). It lacks edge-case details like invalid slugs, but it is complete for basic usage.
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 fully documents the single parameter 'slug' with a description, achieving 100% schema coverage. The tool description adds no additional semantic detail beyond 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 clearly states the tool performs a lookup of a plugin's latest security grade, risk level, and findings count from the WP HealthKit directory. The verb 'look up' and specific resources distinguish it from sibling tools like audit_plugin, which imply active auditing.
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 a read-only lookup scenario, but it does not explicitly state when to use this tool versus alternatives such as audit_plugin. No prerequisites or exclusion criteria are mentioned, leaving the usage context only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Flag a specific finding in an audit as a false positive. The report goes to the WP HealthKit team for review — confirmed patterns result in a scanner rule update preventing this finding in future audits.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | Why this finding is a false positive | |
| auditId | Yes | The audit UUID | |
| findingId | Yes | The finding ID (e.g. 'finding-12') | |
| findingTitle | Yes | The title of the finding |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses a key behavioral trait: the flag is sent to a review team and may result in a scanner rule update, implying the action is not a direct or immediate status change. This provides useful side-effect 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?
Two concise sentences: the first states the action and target, the second explains the follow-up process. No redundant information, and the key details are 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?
The tool is relatively simple with no output schema, but the description sufficiently explains the workflow (flag, review, potential rule update). It lacks any explicit mention of immediate changes to the finding's status or possible error outcomes, but these are not critical for a flagging tool. Overall coverage is solid.
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 all 4 parameters with descriptions (100% coverage), so the description does not need to add parameter details. It adds no new semantic meaning beyond what the schema already provides, meeting the baseline for high 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 clearly states the action ('Flag a specific finding') with a specific resource ('in an audit') and purpose ('as a false positive'). It distinguishes itself from sibling tools like get_findings and get_fix_plan by focusing on the flagging workflow.
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 to report a false positive. However, it does not explicitly state when to use this versus alternatives, nor does it provide any exclusions (e.g., 'do not use for confirmed findings'). The context is present but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a CycloneDX or SPDX Software Bill of Materials (SBOM) for a completed audit. Required for EU Cyber Resilience Act (CRA) compliance. Returns the SBOM JSON.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | SBOM format (default: cyclonedx) | |
| auditId | Yes | UUID of the completed audit |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden. It discloses a key precondition (audit must be completed) and states the output is JSON. However, it does not describe failure behavior, side effects, or permissions, leaving gaps in 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 two sentences, front-loaded with the action verb ('Generate'), and every sentence adds value (function, format, use case, output). No waste 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?
Given the tool's low complexity, full schema coverage, and the description's clear statement of the return type ('Returns the SBOM JSON'), the description is complete. It also adds compliance context and the prerequisite of a completed audit, making it self-sufficient.
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 minimal value beyond the schema: it mentions 'completed audit' for auditId and format names for the enum, but this mostly restates the schema. No additional parameter syntax or examples are given.
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: generating a CycloneDX or SPDX SBOM for a completed audit. It specifies the exact resource (SBOM) and the formats, distinguishing it from sibling tools like get_report or get_findings.
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 ('for a completed audit') and even highlights a compliance driver (EU CRA). However, it does not explicitly state when not to use it or name alternatives, so it falls short of a perfect 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get paginated findings from an audit, optionally filtered by severity or category.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 50) | |
| offset | No | Pagination offset | |
| auditId | Yes | The audit UUID | |
| category | No | Filter by finding category | |
| severity | No | Filter: CRITICAL, HIGH, MEDIUM, or LOW |
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 mentions pagination and optional filtering, which are useful, but omits details like authentication, rate limits, error behavior, or response 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 sentence, front-loaded with the action, and contains no redundant or 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?
The description adequately covers the tool's purpose, pagination, and filtering. While there is no output schema or annotations, the schema is rich and the tool is a straightforward getter, so the description is reasonably complete for basic usage, though it could mention response shape or edge 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 input schema covers all 5 parameters with descriptions (100% coverage), so the baseline is 3. The description's mention of severity/category filters doesn't add semantic detail beyond the schema's own parameter 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 tool gets paginated findings from an audit with optional severity/category filters, using a specific verb and resource. This distinguishes it from sibling tools like get_report or flag_finding.
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 when-to-use guidance or alternatives are provided. The description implies usage for retrieving findings but doesn't state conditions, exclusions, or when other tools might be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full Fix Plan for an audit — every finding with impact, remediation guidance, test steps, confidence, and agent-safety flags. Premium-tier audits may include refactorPlan: systemic refactor plans that eliminate a whole class of bug in one coordinated change (do those first). JSON (default) or Markdown.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | Output format: 'json' (default) or 'md' for Markdown | |
| auditId | Yes | The audit UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears the burden of explaining behavior. It clearly states what the response contains and that format can be JSON or Markdown, and mentions the tier-dependent refactorPlan. However, it does not disclose potential errors, auth requirements, or limitations such as large payloads.
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 long and front-loaded with the core purpose. Every clause adds value, and there is no redundant or filler language.
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 adequately covers the tool's output contents, format options, and special refactorPlan behavior. It lacks mention of error handling, prerequisites beyond auditId, or any pagination, but for a simple retrieval tool with no output schema, it is quite 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 already provides 100% coverage for both parameters, so the baseline is 3. The description reiterates the format option but does not add any additional semantic meaning beyond what the schema defines. No new parameter context 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 starts with 'Get the full Fix Plan for an audit', which clearly identifies the action and resource. It lists the specific contents (impact, remediation, test steps, confidence, agent-safety flags), distinguishing it from siblings like get_findings and get_fix_prompt.
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 is provided. The only usage hint is 'do those first' regarding refactorPlan, which is internal output prioritization, not tool selection. It does not mention exclusions or when to use other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get AI-ready fix prompts for an audit's findings, batched by severity.
| Name | Required | Description | Default |
|---|---|---|---|
| auditId | Yes | The audit UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the behavioral disclosure burden. It adds 'batched by severity,' which is a useful behavioral detail. However, it doesn't clarify the output format, any prerequisites, or potential side effects, though the 'Get' verb implies a read-only operation. This is acceptable but leaves some 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 of 13 words. It states the action ('Get'), the object ('AI-ready fix prompts'), and a key qualifier ('batched by severity') without any filler or repetition. 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?
This is a low-complexity tool with one parameter and no output schema. The description sufficiently conveys the purpose and a high-level view of the return value (prompts batched by severity). While it doesn't describe the exact response structure, for such a simple GET operation, the description is relatively 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 single parameter auditId is fully described in the schema ('The audit UUID'), and the description adds no additional parameter semantics beyond confirming the relationship to an audit's findings. With schema coverage at 100%, the baseline of 3 is appropriate, though the description could have elaborated on expected values or 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 clearly identifies a specific verb ('Get') and a specific resource ('AI-ready fix prompts for an audit's findings'), and adds a scoping detail ('batched by severity'). This distinguishes it from sibling tools like get_findings or get_fix_plan, which focus on raw findings or a fix plan rather than AI-ready prompts.
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 fetching fix prompts for an audit's findings, but provides no explicit alternatives, exclusions, or guidance on when to use this tool versus siblings like get_fix_plan or get_findings. The context is clear but not elaborated beyond the basic purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check the status of a queued or in-progress audit job. Returns status (queued/processing/complete/failed), queue position, progress, and the audit result when complete.
| Name | Required | Description | Default |
|---|---|---|---|
| jobId | Yes | The job UUID returned by audit_plugin or audit_plugin_zip |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosure. It specifies the return contents (status, queue position, progress, audit result when complete), which gives the agent a clear idea of what to expect. It does not detail error behavior or side effects, but the non-mutating nature is evident from 'check the status'.
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 primary purpose, and contains no fluff or redundant details. Every sentence contributes 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 simple one-parameter tool with no output schema, the description adequately covers what the tool does and what it returns. It could be more complete with explicit references to polling behavior or when to use it relative to siblings, but overall it is sufficient.
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 the parameter description already explains the jobId's origin ('returned by audit_plugin or audit_plugin_zip'). The tool description adds no extra parameter semantics beyond the schema, 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?
The description clearly states the tool's purpose with a specific verb ('Check the status') and resource ('queued or in-progress audit job'). It distinguishes this tool from siblings like audit_plugin or get_findings by focusing on job status tracking.
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 is implied rather than explicit: the description indicates it's for checking audit job status, and the schema parameter mentions the jobId comes from audit_plugin or audit_plugin_zip. However, there is no explicit 'when to use' vs alternatives or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the status and results of a completed audit by its audit ID. Use get_job_status to check a job's progress instead.
| Name | Required | Description | Default |
|---|---|---|---|
| auditId | Yes | The audit UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It adds key behavioral context: the audit must be 'completed' and that this returns both status and results. It also implies a read-only operation via 'get'. It does not detail permissions or error cases, but the completed-audit constraint is valuable.
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, both directly informative. No filler, front-loaded with the primary action, and the alternative is clearly stated in the second sentence.
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 read tool with no output schema, the description covers the essential context: what it returns (status and results), required state (completed), and when to use an alternative. It doesn't specify the exact response structure, but this is not critical given the straightforward nature of 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 100% and the parameter is described as 'The audit UUID'. The description only references 'audit ID', which adds little semantic value beyond the schema. Baseline 3 applies because the schema fully documents the 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?
States exactly what it does: get status and results of a completed audit by audit ID. The verb 'get' plus resource clearly identifies the function and distinguishes it from sibling tools like get_job_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?
Explicitly provides an alternative: 'Use get_job_status to check a job's progress instead.' This tells the agent when not to use this tool and directs to the correct sibling, making usage context very clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get aggregated telemetry statistics for a plugin — active installs, version distribution, WP/PHP version breakdown, locale spread, error rates, and daily trend. Requires that your API key is scoped to the plugin or you have a verified plugin claim.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | The WordPress plugin slug (e.g. 'my-plugin', 'woocommerce') | |
| period | No | Stats period (default: 30d) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It explicitly discloses the access requirement (API key scoped or verified claim) and implicitly signals a read-only operation via 'Get'. It does not describe error behavior, but for a stats-retrieval tool, the main behavioral concern (authorization) is addressed.
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 concise: two sentences. The first sentence front-loads the core purpose and data categories, and the second adds necessary access context. No filler or repetition.
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 what the tool returns (a list of statistics) and the access requirement. With no output schema, it does not enumerate the exact response fields beyond the categories, but for a read-only telemetry tool this is sufficiently complete. The period parameter's default is covered by the schema, not 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?
Schema description coverage is 100% and both parameters (slug and period) have meaningful descriptions. The tool description adds no parameter-specific detail beyond what the schema already provides, so it meets the baseline without elevating it.
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 clear resource ('aggregated telemetry statistics for a plugin'), and enumerates the exact statistics provided (active installs, version distribution, WP/PHP breakdown, locale spread, error rates, daily trend). This clearly distinguishes it from sibling tools like audit_plugin or check_plugin, which focus on security audits rather than usage metrics.
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 aggregated telemetry data for a plugin is needed. It also states a prerequisite (API key scoped to the plugin or verified claim). It does not explicitly mention alternatives or exclusions, but the context is clear enough given the sibling tools are unrelated to telemetry.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check your current usage — audits used this month, tier, and limits.
| 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 accurately implies a read-only operation ('check') and discloses the type of data returned. However, it does not explicitly state safety, lack of side effects, or any permissions/rate limits, which would enhance 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, well-structured sentence that front-loads the primary purpose ('Check your current usage') and is concise without unnecessary 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 the tool's simplicity (no parameters, no output schema), the description covers the essential information. It could mention whether the usage data is real-time or how 'this month' is defined, but these are minor gaps for a simple query 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 tool has zero parameters, and the baseline is 4 per the rubric. The description adds useful context by explaining what the tool returns (audits used, tier, limits), going beyond the empty 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's function: checking current usage with specific details (audits used this month, tier, limits). It uses a specific verb ('check') and resource ('your current usage'), distinguishing it from sibling tools focused on audits, plugins, or reports.
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 to check usage) but does not explicitly mention when not to use it or provide alternatives. There is no comparative guidance as seen in well-differentiated tools.
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.
v0.6.2audit_pluginaudit_plugin_zipaudit_plugins_bulkcheck_pluginflag_findinggenerate_sbomget_findingsget_fix_planget_fix_promptget_job_statusget_reportget_telemetry_statslist_usageScored across 13 tools
Most tools have clearly distinct purposes, such as starting audits versus retrieving results or fixes. A few pairs like get_fix_prompt/get_fix_plan and get_job_status/get_report overlap slightly, but their descriptions sufficiently clarify when to use each.
The naming generally follows a verb_noun pattern (audit_plugin, get_findings, generate_sbom). Minor deviations like audit_plugins_bulk and audit_plugin_zip have modifiers at the end, and the mix of get/list/check verbs is consistent but not perfectly uniform.
With 13 tools, the set is well-scoped for a security auditing service. Each tool serves a clear role in the audit lifecycle: initiation, status tracking, result retrieval, fix generation, and supplementary features like SBOM and telemetry.
The core audit workflow is well covered: start audits via slug, ZIP, or bulk; check status; retrieve reports and findings; generate fix prompts/plans; and flag false positives. Minor gaps like a missing list-all-audits or cancel-audit tool are workaroundable.
AI website audit: security, SEO, performance, UX and accessibility checks with actionable fixes.
Threat modeling, code/cloud/pipeline scanning, shadow-AI discovery, compliance checks and fixes.
Security, SEO and AI-visibility scanner for web apps · free scans and focused checks via MCP.
Independent security review for AI-built apps. Watch a GitHub repo. Never a patch.
