Skip to main content
Glama

fileforge_audit_action

Audit a page or site for SEO, content, policy, and client-side security issues; store results or compare runs to track changes.

Instructions

Audit a page or site for SEO, content, policy and client-side security issues. Prefer query_audit with a preset; compare_runs shows what changed between stored audits. Use fileforge_a11y_action, fileforge_perf_action or fileforge_responsive_action for one focused check. reveal_client_security_value needs FILEFORGE_ALLOW_SECRET_REVEAL=1. Results can be stored. Needs the extension.

Input Schema

NameRequiredDescriptionDefault
keyNoStorage key whose value to reveal.
refNoRef of a stored result.
urlNoPage URL. Omit to use the active tab where the action allows it.
textNoPage text to include in the sensitivity check.
queryNoModules to return and their options. Takes priority over preset. Modules: page, seo, accessibility, performance, conversion, visual, technical, privacyTrust, structuredData, links, assets, forms, crawl, scores, issues, roadmap, report, snapshot, summary.
storeNoSave the result in ~/.fileforge and return a ref.
tabIdNoTab ID, or "active" for the active tab.
titleNoPage title to include in the sensitivity check.
actionYesWhat to do. Required parameters are in brackets. query_audit: Unified GraphQL-feel audit. Select audit modules (seo, accessibility, performance, conversion, visual, technical, privacyTrust, structuredData, crawl), presets, scores, issues, roadmap, report, and snapshots in one call. compare_audit_snapshots (beforeSnapshotId, afterSnapshotId): Compare two audit snapshots (by ID) and report score deltas, new issues, resolved issues, and changed modules. site_route (url): Audit site routes and links for broken routes, invalid links, duplicate titles, missing canonicals, redirects, and route health. content_consistency (url): Detect pricing, subscription, feature-count, product-identity, and limitation contradictions across crawled pages. extension_policy (url): Review site/listing/manifest copy for Chrome extension policy and claim-safety risks. client_side_security (url): Inspect client-side storage for Pro/license flags, exposed secrets, debug flags, tokens, and sensitive state with redacted evidence. reveal_client_security_value (url): Reveal one exact redacted client-storage value after an explicit scoped agent request, and log the reveal. recommendations_rank: Deduplicate and rank issues by impact, severity, confidence, project type, and affected pages. compare_runs (beforeRef, afterRef): Compare two stored audit runs for added/resolved issues and high-level performance/evidence changes. export_package (ref): Export a stored audit result as a ZIP package with report.md, issues.json, summary.json, and evidence/result.json. summary (ref): Return a stored audit result in an agent-friendly summary mode such as developer, seo, compliance, conversion, detailed, short, or json-only. sensitive_session_check (url): Classify whether a URL appears sensitive/private before deep authenticated-page scraping.
issuesNoIssues to rank.
presetNoNamed set of query modules.
routesNoRoute paths to visit, such as "/pricing".
targetNoWhat to audit: { url } or { tabId }. Defaults to the active tab.
projectNoProject name that groups stored results.default
afterRefNoRef of the later stored result.
crawlRefNoRef of a stored crawl to reuse.
filenameNoOutput filename.
locationNoExact location returned by the audit.
manifestNoExtension manifest to check.
maxPagesNoMaximum pages to visit.
beforeRefNoRef of the earlier stored result.
maxChecksNoMaximum checks to run.
namespaceNoWeb storage area that holds the value.
listingCopyNoStore listing text to check.
projectTypeNoProject type used to rank issues.generic
summaryModeNoSummary length.short
afterSnapshotIdNoID of the later snapshot.
beforeSnapshotIdNoID of the earlier snapshot.

Output Schema

NameRequiredDescriptionDefault
okYesFalse if the action failed or a check did not pass.
refNoStored result ID, for fileforge_result_action.
dataNoThe result. Its shape depends on the action.
metaNoTool, action and context.
errorNoFailure code and message.
warningsNoNotes about a call that still ran.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed29 schema fields changedv0.3.0
    • changedInput schema / properties / action / description
      Previous value: -"The action to perform. Available actions: query_audit: Unified GraphQL-feel audit. Select audit modules (seo, accessibility, performance, conversion, visual, technical, privacyTrust, structuredData, crawl), presets, scores, issues, roadmap, report, and snapshots in one call. compare_audit_snapshots: Compare two audit snapshots (by ID) and report score deltas, new issues, resolved issues, and changed modules. site_route: Audit site routes and links for broken routes, invalid links, duplicate titles, missing canonicals, redirects, and route health. content_consistency: Detect pricing, subscription, feature-count, product-identity, and limitation contradictions across crawled pages. extension_policy: Review site/listing/manifest copy for Chrome extension policy and claim-safety risks. client_side_security: Inspect client-side storage for Pro/license flags, exposed secrets, debug flags, tokens, and sensitive state with redacted evidence. reveal_client_security_value: Reveal one exact redacted client-storage value after an explicit scoped agent request, and log the reveal. recommendations_rank: Deduplicate and rank issues by impact, severity, confidence, project type, and affected pages. compare_runs: Compare two stored audit runs for added/resolved issues and high-level performance/evidence changes. export_package: Export a stored audit result as a ZIP package with report.md, issues.json, summary.json, and evidence/result.json. summary: Return a stored audit result in an agent-friendly summary mode such as developer, seo, compliance, conversion, detailed, short, or json-only. sensitive_session_check: Classify whether a URL appears sensitive/private before deep authenticated-page scraping."New value: +"What to do. Required parameters are in brackets. query_audit: Unified GraphQL-feel audit. Select audit modules (seo, accessibility, performance, conversion, visual, technical, privacyTrust, structuredData, crawl), presets, scores, issues, roadmap, report, and snapshots in one call. compare_audit_snapshots (beforeSnapshotId, afterSnapshotId): Compare two audit snapshots (by ID) and report score deltas, new issues, resolved issues, and changed modules. site_route (url): Audit site routes and links for broken routes, invalid links, duplicate titles, missing canonicals, redirects, and route health. content_consistency (url): Detect pricing, subscription, feature-count, product-identity, and limitation contradictions across crawled pages. extension_policy (url): Review site/listing/manifest copy for Chrome extension policy and claim-safety risks. client_side_security (url): Inspect client-side storage for Pro/license flags, exposed secrets, debug flags, tokens, and sensitive state with redacted evidence. reveal_client_security_value (url): Reveal one exact redacted client-storage value after an explicit scoped agent request, and log the reveal. recommendations_rank: Deduplicate and rank issues by impact, severity, confidence, project type, and affected pages. compare_runs (beforeRef, afterRef): Compare two stored audit runs for added/resolved issues and high-level performance/evidence changes. export_package (ref): Export a stored audit result as a ZIP package with report.md, issues.json, summary.json, and evidence/result.json. summary (ref): Return a stored audit result in an agent-friendly summary mode such as developer, seo, compliance, conversion, detailed, short, or json-only. sensitive_session_check (url): Classify whether a URL appears sensitive/private before deep authenticated-page scraping."
    • addedInput schema / properties / afterRef / description
      Added value: +"Ref of the later stored result."
    • addedInput schema / properties / afterSnapshotId / description
      Added value: +"ID of the later snapshot."
    • addedInput schema / properties / beforeRef / description
      Added value: +"Ref of the earlier stored result."
    • addedInput schema / properties / beforeSnapshotId / description
      Added value: +"ID of the earlier snapshot."
    • addedInput schema / properties / crawlRef / description
      Added value: +"Ref of a stored crawl to reuse."
    • addedInput schema / properties / filename / description
      Added value: +"Output filename."
    • addedInput schema / properties / issues / description
      Added value: +"Issues to rank."
    • addedInput schema / properties / key / description
      Added value: +"Storage key whose value to reveal."
    • addedInput schema / properties / listingCopy / description
      Added value: +"Store listing text to check."
    • addedInput schema / properties / location / description
      Added value: +"Exact location returned by the audit."
    • addedInput schema / properties / manifest / description
      Added value: +"Extension manifest to check."
    • addedInput schema / properties / maxChecks / description
      Added value: +"Maximum checks to run."
    • addedInput schema / properties / maxPages / description
      Added value: +"Maximum pages to visit."
    • addedInput schema / properties / namespace / description
      Added value: +"Web storage area that holds the value."
    • addedInput schema / properties / preset / description
      Added value: +"Named set of query modules."
    • addedInput schema / properties / project / description
      Added value: +"Project name that groups stored results."
    • addedInput schema / properties / projectType / description
      Added value: +"Project type used to rank issues."
    • addedInput schema / properties / query / description
      Added value: +"Modules to return and their options. Takes priority over preset. Modules: page, seo, accessibility, performance, conversion, visual, technical, privacyTrust, structuredData, links, assets, forms, crawl, scores, issues, roadmap, report, snapshot, summary."
    • addedInput schema / properties / ref / description
      Added value: +"Ref of a stored result."
    • addedInput schema / properties / routes / description
      Added value: +"Route paths to visit, such as \"/pricing\"."
    • addedInput schema / properties / store / description
      Added value: +"Save the result in ~/.fileforge and return a ref."
    • addedInput schema / properties / summaryMode / description
      Added value: +"Summary length."
    • addedInput schema / properties / tabId / description
      Added value: +"Tab ID, or \"active\" for the active tab."
    • addedInput schema / properties / target / description
      Added value: +"What to audit: { url } or { tabId }. Defaults to the active tab."
    • addedInput schema / properties / text / description
      Added value: +"Page text to include in the sensitivity check."
    • addedInput schema / properties / title / description
      Added value: +"Page title to include in the sensitivity check."
    • addedInput schema / properties / url / description
      Added value: +"Page URL. Omit to use the active tab where the action allows it."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "description": "query_* actions return their modules as extra top-level fields.",
      +  "properties": {
      +    "data": {
      +      "description": "The result. Its shape depends on the action."
      +    },
      +    "error": {
      +      "description": "Failure code and message."
      +    },
      +    "meta": {
      +      "description": "Tool, action and context."
      +    },
      +    "ok": {
      +      "description": "False if the action failed or a check did not pass.",
      +      "type": "boolean"
      +    },
      +    "ref": {
      +      "description": "Stored result ID, for fileforge_result_action."
      +    },
      +    "warnings": {
      +      "description": "Notes about a call that still ran."
      +    }
      +  },
      +  "required": [
      +    "ok"
      +  ],
      +  "type": "object"
      +}
  2. First observedv0.2.1

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds real context beyond the annotations: it discloses the extension prerequisite and the FILEFORGE_ALLOW_SECRET_REVEAL=1 environment gate for reveal_client_security_value, plus that 'Results can be stored', consistent with readOnlyHint=false. However, it does not state where results are persisted, that the reveal is logged as an audited action (only the schema says so), or the open-world cost of crawling a site under openWorldHint=true.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Five short sentences, front-loaded with the purpose and then the routing rules, with no filler. The reveal_client_security_value env-var sentence sits mid-paragraph rather than grouped with the other prerequisites, which slightly interrupts the flow.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 28-parameter, 12-action dispatcher with an output schema, the description covers purpose, preferred entry point, sibling delegation, two hard prerequisites, and storage behavior. The gaps are the unmentioned action modes, which the enum's own descriptions handle, so the definition is largely self-sufficient for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter, including the per-action required-parameter list inside the action enum description, is already documented. The description only adds that query_audit takes a preset and that compare_runs works on stored audits, which is largely a restatement. Baseline 3 applies when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific verb and resource ('Audit a page or site for SEO, content, policy and client-side security issues') and names three sibling tools it is not. The multi-action dispatcher nature is only partly visible in the description, but the primary action (query_audit) and the main alternatives are surfaced, which is enough to distinguish it from the 25 siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing guidance: 'Prefer query_audit with a preset' selects the default path, 'compare_runs shows what changed between stored audits' scopes the comparison action, and three sibling tools are named for single-focus checks. It stops short of covering when to use the remaining nine actions (site_route, extension_policy, sensitive_session_check, etc.), which the schema action enum must carry.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.