@automatelab/ai-seo-mcp 0.3.4 → 0.5.0

package/dist/index.js

@@ -22,10 +22,11 @@ import { diffPages, diffPagesInputSchema } from "./tools/diff-pages.js";
 import { auditSite, auditSiteInputSchema } from "./tools/audit-site.js";
 import { auditSitemap, auditSitemapInputSchema } from "./tools/audit-sitemap.js";
 import { saveAuditReport, saveAuditReportInputSchema } from "./tools/save-audit-report.js";
+import { auditPageOutputShape, auditSchemaOutputShape, auditCanonicalOutputShape, auditSiteOutputShape, auditSitemapOutputShape, checkRobotsOutputShape, checkSitemapOutputShape, checkTechnicalOutputShape, scoreAiOverviewOutputShape, scoreCitationOutputShape, generateLlmsTxtOutputShape, validateLlmsTxtOutputShape, rewriteOutputShape, extractEntitiesOutputShape, testCitationOutputShape, diffPagesOutputShape, saveReportOutputShape, } from "./output-schemas.js";
 import { ToolFetchError } from "./lib/fetch.js";
 const server = new McpServer({
     name: "@automatelab/ai-seo-mcp",
-    version: "0.3.4",
+    version: "0.4.1",
 });
 /** Serialize a ToolError to MCP error content. */
 function toolError(err) {
@@ -34,11 +35,17 @@ function toolError(err) {
         isError: true,
     };
 }
-/** Wrap a tool handler to catch errors and return structured ToolError responses. */
+/**
+ * Wrap a tool handler:
+ * - On success, returns both `content` (JSON text for legacy clients) and
+ *   `structuredContent` (parsed object validated against the tool's outputSchema).
+ * - On failure, returns a typed ToolError as a text-only error response.
+ */
 function wrapHandler(handler) {
     return handler()
         .then((result) => ({
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        structuredContent: result,
     }))
         .catch((err) => {
         if (err instanceof ToolFetchError) {
@@ -49,320 +56,555 @@ function wrapHandler(handler) {
         return toolError({ type: "fetch_error", url: "", message });
     });
 }
-// --- Tool 1: audit_page ---
-server.tool("audit_page", [
-    "Full AI-SEO audit of a single URL: returns categorized findings (info/warning/error) with severity, fix instructions, and a 0-100 composite score plus per-dimension subscores.",
-    "Read-only. Fetches the URL once and runs every sub-audit (schema, robots, technical, sitemap, AI-Overview eligibility) against the response. No writes, no third-party APIs, no auth required, no rate limits beyond polite per-host throttling.",
-    "Deterministic, rule-based scoring; no LLM calls. Same URL + same input flags returns the same score.",
-    "Supports `render: \"static\" | \"headless\"`. Default `static` (fast, raw HTML only). Use `headless` for React/Vue/Angular SPAs — adds 3-10s and requires the optional `playwright-core` peer dep plus a one-time `npx playwright install chromium`.",
-    "When to use: the default entry point for `audit any page`. Use this instead of calling check_technical / audit_schema / check_robots / check_sitemap / score_ai_overview_eligibility individually unless you specifically need only one dimension - this tool composes all of them.",
-].join("\n\n"), auditPageInputSchema.shape, async (input) => wrapHandler(() => auditPage(input)));
-// --- Tool 2: audit_schema ---
-server.tool("audit_schema", [
-    "Validate JSON-LD structured data against Schema.org rules and AI-citation best practices. Accepts either a URL (fetched) or a raw JSON string (parsed directly).",
-    "Read-only when given `url` (one HTTP GET). Zero network when given `schema_json`. No writes.",
-    "Deterministic, rule-based; no LLM. Validates required/recommended properties, @context correctness, sameAs links, and AI-search-friendly patterns.",
-    "When to use: focused JSON-LD audits, or to validate a schema block you're about to ship. For a full page audit that includes schema + everything else, use `audit_page` instead.",
-    "Either `url` or `schema_json` must be provided (not both). If both are provided, `schema_json` wins and no fetch happens.",
-].join("\n\n"), {
-    url: z
-        .string()
-        .url()
-        .optional()
-        .describe("Public URL to fetch and audit. Either this OR `schema_json` is required. Read-only HTTP GET."),
-    schema_json: z
-        .string()
-        .optional()
-        .describe("Raw JSON-LD as a string (the contents of a `<script type=\"application/ld+json\">` block). Use this to validate a schema block offline without fetching a URL. Either this OR `url` is required."),
-    respect_robots: z
-        .boolean()
-        .optional()
-        .default(true)
-        .describe("If true (default), respect robots.txt before fetching `url`. Ignored when `schema_json` is used."),
+// ---------------------------------------------------------------------------
+// Tool naming convention: dot-notation forms a navigable tree.
+//   audit.*    - composite audits that fetch and analyse a page or site
+//   check.*    - focused single-dimension checks (robots, sitemap, technical)
+//   score.*    - numeric scoring of citation / AI-Overview eligibility / cite-or-not
+//   llms_txt.* - generate / validate llms.txt files
+//   rewrite.*  - LLM-assisted content rewrites (delegated via MCP sampling)
+//   extract.*  - entity / structure extraction
+//   diff.*     - comparisons between pages
+//   report.*   - report rendering and storage
+// Renamed in v0.4.0 from the previous flat snake_case names.
+// ---------------------------------------------------------------------------
+// --- audit.page ---
+server.registerTool("audit.page", {
+    title: "Audit page (full)",
+    description: [
+        "Full AI-SEO audit of a single URL: returns categorized findings (info/warning/error) with severity, fix instructions, and a 0-100 composite score plus per-dimension subscores.",
+        "Read-only. Fetches the URL once and runs every sub-audit (schema, robots, technical, sitemap, AI-Overview eligibility) against the response. No writes, no third-party APIs, no auth required, no rate limits beyond polite per-host throttling.",
+        "Deterministic, rule-based scoring; no LLM calls. Same URL + same input flags returns the same score.",
+        "Supports `render: \"static\" | \"headless\"`. Default `static` (fast, raw HTML only). Use `headless` for React/Vue/Angular SPAs — adds 3-10s and requires the optional `playwright-core` peer dep plus a one-time `npx playwright install chromium`.",
+        "When to use: the default entry point for `audit any page`. Use this instead of calling check.technical / audit.schema / check.robots / check.sitemap / score.ai_overview_eligibility individually unless you specifically need only one dimension - this tool composes all of them.",
+    ].join("\n\n"),
+    inputSchema: auditPageInputSchema.shape,
+    outputSchema: auditPageOutputShape,
+    annotations: {
+        title: "Audit page (full)",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+}, async (input) => wrapHandler(() => auditPage(input)));
+// --- audit.schema ---
+server.registerTool("audit.schema", {
+    title: "Audit JSON-LD schema",
+    description: [
+        "Validate JSON-LD structured data against Schema.org rules and AI-citation best practices. Accepts either a URL (fetched) or a raw JSON string (parsed directly).",
+        "Read-only when given `url` (one HTTP GET). Zero network when given `schema_json`. No writes.",
+        "Deterministic, rule-based; no LLM. Validates required/recommended properties, @context correctness, sameAs links, and AI-search-friendly patterns.",
+        "When to use: focused JSON-LD audits, or to validate a schema block you're about to ship. For a full page audit that includes schema + everything else, use `audit.page` instead.",
+        "Either `url` or `schema_json` must be provided (not both). If both are provided, `schema_json` wins and no fetch happens.",
+    ].join("\n\n"),
+    inputSchema: {
+        url: z
+            .string()
+            .url()
+            .optional()
+            .describe("Public URL to fetch and audit. Either this OR `schema_json` is required. Read-only HTTP GET."),
+        schema_json: z
+            .string()
+            .optional()
+            .describe("Raw JSON-LD as a string (the contents of a `<script type=\"application/ld+json\">` block). Use this to validate a schema block offline without fetching a URL. Either this OR `url` is required."),
+        respect_robots: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("If true (default), respect robots.txt before fetching `url`. Ignored when `schema_json` is used."),
+    },
+    outputSchema: auditSchemaOutputShape,
+    annotations: {
+        title: "Audit JSON-LD schema",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
 }, async (input) => {
     if (!input.url && !input.schema_json) {
         return toolError({ type: "invalid_url", message: "One of url or schema_json is required" });
     }
     return wrapHandler(() => auditSchema(input));
 });
-// --- Tool 3: audit_canonical ---
-server.tool("audit_canonical", [
-    "Audit a page's canonical link integrity: presence, self-reference, cross-domain mismatches, trailing-slash hygiene, and og:url consistency.",
-    "Read-only. One HTTP GET to fetch the HEAD section.",
-    "Deterministic, rule-based; no LLM.",
-    "When to use: a focused canonical-only audit (e.g. debugging a duplicate-content issue). For a full HEAD audit including OpenGraph, hreflang, noindex, title, use `check_technical`. For everything-on-a-page, use `audit_page`.",
-].join("\n\n"), auditCanonicalInputSchema.shape, async (input) => wrapHandler(() => auditCanonical(input)));
-// --- Tool 4: check_robots ---
-server.tool("check_robots", [
-    "Fetch and parse a domain's robots.txt; report per-crawler allow/disallow posture for every known AI training crawler (GPTBot, CCBot, Anthropic-AI, Google-Extended, etc.), AI search crawlers (ChatGPT-User, PerplexityBot, OAI-SearchBot), and user-triggered fetchers.",
-    "Read-only. One HTTP GET to /robots.txt. No auth, no rate limits applied.",
-    "Deterministic, rule-based; no LLM. Returns structured findings with per-crawler status.",
-    "When to use: figuring out which AI crawlers a site blocks vs allows. Combine with `check_sitemap` for a full pre-crawl audit. Distinct from `audit_page` which evaluates a single URL; this evaluates a whole-domain policy.",
-].join("\n\n"), checkRobotsInputSchema.shape, async (input) => wrapHandler(() => checkRobots(input)));
-// --- Tool 5: check_sitemap ---
-server.tool("check_sitemap", [
-    "Validate a domain's XML sitemap: presence, accessibility, URL count, lastmod freshness, sitemap-index handling, and image/video sitemap extensions.",
-    "Read-only. Issues N+1 HTTP GETs: one for robots.txt + sitemap, then up to `max_urls_to_check` HEADs against sampled URLs.",
-    "Deterministic, rule-based; no LLM.",
-    "When to use: site-wide indexing audits. Pair with `check_robots` for a full pre-crawl picture. For per-page checks, use `audit_page` or `check_technical` instead.",
-].join("\n\n"), checkSitemapInputSchema.shape, async (input) => wrapHandler(() => checkSitemap(input)));
-// --- Tool 6: check_technical ---
-server.tool("check_technical", [
-    "Audit a page's HEAD section for technical signals relevant to AI crawlers: HTTPS, canonical, OpenGraph, Twitter Card, hreflang, noindex, and title-vs-H1 hygiene.",
-    "Read-only. One HTTP GET, inspects HEAD only (body is not parsed).",
-    "Deterministic, rule-based; no LLM.",
-    "When to use: when you specifically need HEAD-tag audit findings. For the full page including schema and AI-Overview scoring, use `audit_page`. For canonical-only, use `audit_canonical`.",
-].join("\n\n"), checkTechnicalInputSchema.shape, async (input) => wrapHandler(() => checkTechnical(input)));
-// --- Tool 7: score_ai_overview_eligibility ---
-server.tool("score_ai_overview_eligibility", [
-    "Score a page's probability of appearing in Google AI Overviews. Returns an overall 0-100 score plus six factor subscores: semantic completeness, structured data, E-E-A-T signals, entity density, freshness, and technical hygiene.",
-    "Read-only. One HTTP GET.",
-    "Deterministic, rule-based scoring derived from published 2025-2026 AI-Overview correlation studies. No LLM calls. Same URL returns the same score on repeated runs.",
-    "When to use: AI-Overview-specific prioritization. For a multi-dimensional audit that includes this scoring plus everything else, use `audit_page`. For citation-worthiness of a specific text passage (rather than a URL ranking probability), use `score_citation_worthiness`.",
-].join("\n\n"), scoreAiOverviewEligibilityInputSchema.shape, async (input) => wrapHandler(() => scoreAiOverviewEligibility(input)));
-// --- Tool 8: generate_llms_txt ---
-server.tool("generate_llms_txt", [
-    "Generate a spec-compliant llms.txt (and optionally llms-full.txt) for a domain by reading its sitemap, sampling up to `max_pages` pages, and synthesizing a grouped, sectioned summary.",
-    "Read-only. Issues one HTTP GET for the sitemap then one per sampled page.",
-    "Deterministic; no LLM. Output is the file content as a string - this tool does NOT write to disk or upload anywhere. The caller is responsible for hosting the resulting file at `https://<domain>/llms.txt`.",
-    "When to use: bootstrapping llms.txt for a site you own. To check an existing llms.txt, use `validate_llms_txt` instead.",
-].join("\n\n"), generateLlmsTxtInputSchema.shape, async (input) => wrapHandler(() => generateLlmsTxtTool(input)));
-// --- Tool 9: validate_llms_txt ---
-server.tool("validate_llms_txt", [
-    "Validate an existing llms.txt or llms-full.txt against the spec: structure, section ordering, link format, and (optionally) broken-link detection.",
-    "Read-only. One HTTP GET when given `url`; zero network when given `content`. Optional link-check issues HEAD requests against each link if `check_links` is true.",
-    "Deterministic; no LLM.",
-    "When to use: auditing an llms.txt you already have. To generate one from scratch, use `generate_llms_txt`.",
-    "Either `url` or `content` must be provided.",
-].join("\n\n"), {
-    url: z
-        .string()
-        .url()
-        .optional()
-        .describe("Public URL of an existing llms.txt or llms-full.txt to validate (e.g. `https://example.com/llms.txt`). Either this OR `content` is required."),
-    content: z
-        .string()
-        .optional()
-        .describe("Raw llms.txt content as a string. Use this to validate a file offline without fetching. Either this OR `url` is required."),
-    check_links: z
-        .boolean()
-        .optional()
-        .default(true)
-        .describe("If true (default), HEAD each linked URL to detect broken links. Set false to skip link checks for faster, network-light validation of just the structural rules."),
+// --- audit.canonical ---
+server.registerTool("audit.canonical", {
+    title: "Audit canonical link integrity",
+    description: [
+        "Audit a page's canonical link integrity: presence, self-reference, cross-domain mismatches, trailing-slash hygiene, and og:url consistency.",
+        "Read-only. One HTTP GET to fetch the HEAD section.",
+        "Deterministic, rule-based; no LLM.",
+        "When to use: a focused canonical-only audit (e.g. debugging a duplicate-content issue). For a full HEAD audit including OpenGraph, hreflang, noindex, title, use `check.technical`. For everything-on-a-page, use `audit.page`.",
+    ].join("\n\n"),
+    inputSchema: auditCanonicalInputSchema.shape,
+    outputSchema: auditCanonicalOutputShape,
+    annotations: {
+        title: "Audit canonical link integrity",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+}, async (input) => wrapHandler(() => auditCanonical(input)));
+// --- check.robots ---
+server.registerTool("check.robots", {
+    title: "Check robots.txt crawler posture",
+    description: [
+        "Fetch and parse a domain's robots.txt; report per-crawler allow/disallow posture for every known AI training crawler (GPTBot, CCBot, Anthropic-AI, Google-Extended, etc.), AI search crawlers (ChatGPT-User, PerplexityBot, OAI-SearchBot), and user-triggered fetchers.",
+        "Read-only. One HTTP GET to /robots.txt. No auth, no rate limits applied.",
+        "Deterministic, rule-based; no LLM. Returns structured findings with per-crawler status.",
+        "When to use: figuring out which AI crawlers a site blocks vs allows. Combine with `check.sitemap` for a full pre-crawl audit. Distinct from `audit.page` which evaluates a single URL; this evaluates a whole-domain policy.",
+    ].join("\n\n"),
+    inputSchema: checkRobotsInputSchema.shape,
+    outputSchema: checkRobotsOutputShape,
+    annotations: {
+        title: "Check robots.txt crawler posture",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+}, async (input) => wrapHandler(() => checkRobots(input)));
+// --- check.sitemap ---
+server.registerTool("check.sitemap", {
+    title: "Check XML sitemap health",
+    description: [
+        "Validate a domain's XML sitemap: presence, accessibility, URL count, lastmod freshness, sitemap-index handling, and image/video sitemap extensions.",
+        "Read-only. Issues N+1 HTTP GETs: one for robots.txt + sitemap, then up to `max_urls_to_check` HEADs against sampled URLs.",
+        "Deterministic, rule-based; no LLM.",
+        "When to use: site-wide indexing audits. Pair with `check.robots` for a full pre-crawl picture. For per-page checks, use `audit.page` or `check.technical` instead.",
+    ].join("\n\n"),
+    inputSchema: checkSitemapInputSchema.shape,
+    outputSchema: checkSitemapOutputShape,
+    annotations: {
+        title: "Check XML sitemap health",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+}, async (input) => wrapHandler(() => checkSitemap(input)));
+// --- check.technical ---
+server.registerTool("check.technical", {
+    title: "Check technical HEAD signals",
+    description: [
+        "Audit a page's HEAD section for technical signals relevant to AI crawlers: HTTPS, canonical, OpenGraph, Twitter Card, hreflang, noindex, and title-vs-H1 hygiene.",
+        "Read-only. One HTTP GET, inspects HEAD only (body is not parsed).",
+        "Deterministic, rule-based; no LLM.",
+        "When to use: when you specifically need HEAD-tag audit findings. For the full page including schema and AI-Overview scoring, use `audit.page`. For canonical-only, use `audit.canonical`.",
+    ].join("\n\n"),
+    inputSchema: checkTechnicalInputSchema.shape,
+    outputSchema: checkTechnicalOutputShape,
+    annotations: {
+        title: "Check technical HEAD signals",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+}, async (input) => wrapHandler(() => checkTechnical(input)));
+// --- score.ai_overview_eligibility ---
+server.registerTool("score.ai_overview_eligibility", {
+    title: "Score AI Overview eligibility",
+    description: [
+        "Score a page's probability of appearing in Google AI Overviews. Returns an overall 0-100 score plus six factor subscores: semantic completeness, structured data, E-E-A-T signals, entity density, freshness, and technical hygiene.",
+        "Read-only. One HTTP GET.",
+        "Deterministic, rule-based scoring derived from published 2025-2026 AI-Overview correlation studies. No LLM calls. Same URL returns the same score on repeated runs.",
+        "When to use: AI-Overview-specific prioritization. For a multi-dimensional audit that includes this scoring plus everything else, use `audit.page`. For citation-worthiness of a specific text passage (rather than a URL ranking probability), use `score.citation_worthiness`.",
+    ].join("\n\n"),
+    inputSchema: scoreAiOverviewEligibilityInputSchema.shape,
+    outputSchema: scoreAiOverviewOutputShape,
+    annotations: {
+        title: "Score AI Overview eligibility",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+}, async (input) => wrapHandler(() => scoreAiOverviewEligibility(input)));
+// --- llms_txt.generate ---
+server.registerTool("llms_txt.generate", {
+    title: "Generate llms.txt",
+    description: [
+        "Generate a spec-compliant llms.txt (and optionally llms-full.txt) for a domain by reading its sitemap, sampling up to `max_pages` pages, and synthesizing a grouped, sectioned summary.",
+        "Read-only. Issues one HTTP GET for the sitemap then one per sampled page.",
+        "Deterministic; no LLM. Output is the file content as a string - this tool does NOT write to disk or upload anywhere. The caller is responsible for hosting the resulting file at `https://<domain>/llms.txt`.",
+        "When to use: bootstrapping llms.txt for a site you own. To check an existing llms.txt, use `llms_txt.validate` instead.",
+    ].join("\n\n"),
+    inputSchema: generateLlmsTxtInputSchema.shape,
+    outputSchema: generateLlmsTxtOutputShape,
+    annotations: {
+        title: "Generate llms.txt",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+}, async (input) => wrapHandler(() => generateLlmsTxtTool(input)));
+// --- llms_txt.validate ---
+server.registerTool("llms_txt.validate", {
+    title: "Validate llms.txt",
+    description: [
+        "Validate an existing llms.txt or llms-full.txt against the spec: structure, section ordering, link format, and (optionally) broken-link detection.",
+        "Read-only. One HTTP GET when given `url`; zero network when given `content`. Optional link-check issues HEAD requests against each link if `check_links` is true.",
+        "Deterministic; no LLM.",
+        "When to use: auditing an llms.txt you already have. To generate one from scratch, use `llms_txt.generate`.",
+        "Either `url` or `content` must be provided.",
+    ].join("\n\n"),
+    inputSchema: {
+        url: z
+            .string()
+            .url()
+            .optional()
+            .describe("Public URL of an existing llms.txt or llms-full.txt to validate (e.g. `https://example.com/llms.txt`). Either this OR `content` is required."),
+        content: z
+            .string()
+            .optional()
+            .describe("Raw llms.txt content as a string. Use this to validate a file offline without fetching. Either this OR `url` is required."),
+        check_links: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("If true (default), HEAD each linked URL to detect broken links. Set false to skip link checks for faster, network-light validation of just the structural rules."),
+    },
+    outputSchema: validateLlmsTxtOutputShape,
+    annotations: {
+        title: "Validate llms.txt",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
 }, async (input) => {
     if (!input.url && !input.content) {
         return toolError({ type: "invalid_url", message: "One of url or content is required" });
     }
     return wrapHandler(() => validateLlmsTxt(input));
 });
-// --- Tool 10: score_citation_worthiness ---
-server.tool("score_citation_worthiness", [
-    "Score how citable a page or text block is for AI engines (ChatGPT, Claude, Perplexity, Google AI Overviews). Evaluates BLUF (bottom-line-up-front) opening, FAQ patterns, statistic density, entity clarity, and answer-shape fit for the optional `target_query`.",
-    "Read-only when given `url` (one HTTP GET). Zero network when given `text`. No writes.",
-    "Deterministic, rule-based; no LLM calls. Returns reproducible scores.",
-    "When to use: pre-publish content QA, or to triage which existing pages are worth optimizing for AI citation first. Distinct from `score_ai_overview_eligibility` which scores Google-AI-Overview ranking probability for a URL; this scores the inherent citability of a text passage regardless of host.",
-    "Either `url` or `text` must be provided.",
-].join("\n\n"), {
-    url: z
-        .string()
-        .url()
-        .optional()
-        .describe("Public URL to fetch and score. Either this OR `text` is required."),
-    text: z
-        .string()
-        .optional()
-        .describe("Raw text/markdown/HTML to score directly without fetching. Either this OR `url` is required."),
-    target_query: z
-        .string()
-        .optional()
-        .describe("Optional target search query the content is supposed to answer (e.g. `how to fix CORS errors in Next.js`). When provided, scoring weights answer-shape fit and query-term coverage. Omit if you want a query-agnostic citability score."),
-    respect_robots: z
-        .boolean()
-        .optional()
-        .default(true)
-        .describe("If true (default), respect robots.txt when fetching `url`. Ignored when `text` is used."),
+// --- score.citation_worthiness ---
+server.registerTool("score.citation_worthiness", {
+    title: "Score AI citation worthiness",
+    description: [
+        "Score how citable a page or text block is for AI engines (ChatGPT, Claude, Perplexity, Google AI Overviews). Evaluates BLUF (bottom-line-up-front) opening, FAQ patterns, statistic density, entity clarity, and answer-shape fit for the optional `target_query`.",
+        "Read-only when given `url` (one HTTP GET). Zero network when given `text`. No writes.",
+        "Deterministic, rule-based; no LLM calls. Returns reproducible scores.",
+        "When to use: pre-publish content QA, or to triage which existing pages are worth optimizing for AI citation first. Distinct from `score.ai_overview_eligibility` which scores Google-AI-Overview ranking probability for a URL; this scores the inherent citability of a text passage regardless of host.",
+        "Either `url` or `text` must be provided.",
+    ].join("\n\n"),
+    inputSchema: {
+        url: z
+            .string()
+            .url()
+            .optional()
+            .describe("Public URL to fetch and score. Either this OR `text` is required."),
+        text: z
+            .string()
+            .optional()
+            .describe("Raw text/markdown/HTML to score directly without fetching. Either this OR `url` is required."),
+        target_query: z
+            .string()
+            .optional()
+            .describe("Optional target search query the content is supposed to answer (e.g. `how to fix CORS errors in Next.js`). When provided, scoring weights answer-shape fit and query-term coverage. Omit if you want a query-agnostic citability score."),
+        respect_robots: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("If true (default), respect robots.txt when fetching `url`. Ignored when `text` is used."),
+    },
+    outputSchema: scoreCitationOutputShape,
+    annotations: {
+        title: "Score AI citation worthiness",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
 }, async (input) => {
     if (!input.url && !input.text) {
         return toolError({ type: "invalid_url", message: "One of url or text is required" });
     }
     return wrapHandler(() => scoreCitationWorthiness(input));
 });
-// --- Tool 11: rewrite_for_aeo ---
-server.tool("rewrite_for_aeo", [
-    "Rewrite a content block for Answer Engine Optimization. Adds a BLUF opening, FAQ structure, schema additions, and concise question-shaped headings tuned for ChatGPT / Perplexity / Google AI Overviews.",
-    "Read-only when given `url` (one HTTP GET). Zero network when given `text`. The tool does NOT write back to the URL - it only returns the rewritten content as a string. No side effects on the source.",
-    "This tool delegates the actual rewrite to the calling LLM via MCP sampling - it does not call any external API itself. The MCP host's model produces the rewrite. Same input may produce different output across runs (model-dependent).",
-    "When to use: optimizing content for direct-answer surfaces (definitions, how-tos, FAQs). For Generative Engine Optimization (entity-rich, comparison-ready synthesis), use `rewrite_for_geo` instead.",
-    "Either `url` or `text` must be provided. `target_query` is required.",
-].join("\n\n"), {
-    url: z
-        .string()
-        .url()
-        .optional()
-        .describe("Public URL whose content should be fetched and rewritten. Either this OR `text` is required."),
-    text: z
-        .string()
-        .optional()
-        .describe("Raw content (markdown or HTML) to rewrite directly. Either this OR `url` is required."),
-    target_query: z
-        .string()
-        .describe("The user query the rewrite should answer (e.g. `what is RAG`, `how to deploy Ghost to Docker`). Required - drives heading shape and BLUF wording."),
-    format: z
-        .enum(["article", "faq", "howto", "comparison"])
-        .default("article")
-        .describe("Output shape. `article` for prose-with-headings. `faq` for Q&A list. `howto` for numbered-step procedural content with HowTo schema hints. `comparison` for X-vs-Y tables. Default `article`."),
-    max_words: z
-        .number()
-        .int()
-        .min(100)
-        .max(5000)
-        .optional()
-        .default(1500)
-        .describe("Soft word budget for the rewrite. Default 1500. Range 100-5000. The rewrite tries to stay under this; very small budgets may force truncation."),
-    respect_robots: z
-        .boolean()
-        .optional()
-        .default(true)
-        .describe("If true (default), respect robots.txt when fetching `url`. Ignored when `text` is used."),
+// --- rewrite.aeo ---
+server.registerTool("rewrite.aeo", {
+    title: "Rewrite for Answer Engine Optimization",
+    description: [
+        "Rewrite a content block for Answer Engine Optimization. Adds a BLUF opening, FAQ structure, schema additions, and concise question-shaped headings tuned for ChatGPT / Perplexity / Google AI Overviews.",
+        "Read-only when given `url` (one HTTP GET). Zero network when given `text`. The tool does NOT write back to the URL - it only returns the rewritten content as a string. No side effects on the source.",
+        "This tool delegates the actual rewrite to the calling LLM via MCP sampling - it does not call any external API itself. The MCP host's model produces the rewrite. Same input may produce different output across runs (model-dependent).",
+        "When to use: optimizing content for direct-answer surfaces (definitions, how-tos, FAQs). For Generative Engine Optimization (entity-rich, comparison-ready synthesis), use `rewrite.geo` instead.",
+        "Either `url` or `text` must be provided. `target_query` is required.",
+    ].join("\n\n"),
+    inputSchema: {
+        url: z
+            .string()
+            .url()
+            .optional()
+            .describe("Public URL whose content should be fetched and rewritten. Either this OR `text` is required."),
+        text: z
+            .string()
+            .optional()
+            .describe("Raw content (markdown or HTML) to rewrite directly. Either this OR `url` is required."),
+        target_query: z
+            .string()
+            .describe("The user query the rewrite should answer (e.g. `what is RAG`, `how to deploy Ghost to Docker`). Required - drives heading shape and BLUF wording."),
+        format: z
+            .enum(["article", "faq", "howto", "comparison"])
+            .default("article")
+            .describe("Output shape. `article` for prose-with-headings. `faq` for Q&A list. `howto` for numbered-step procedural content with HowTo schema hints. `comparison` for X-vs-Y tables. Default `article`."),
+        max_words: z
+            .number()
+            .int()
+            .min(100)
+            .max(5000)
+            .optional()
+            .default(1500)
+            .describe("Soft word budget for the rewrite. Default 1500. Range 100-5000. The rewrite tries to stay under this; very small budgets may force truncation."),
+        respect_robots: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("If true (default), respect robots.txt when fetching `url`. Ignored when `text` is used."),
+    },
+    outputSchema: rewriteOutputShape,
+    annotations: {
+        title: "Rewrite for Answer Engine Optimization",
+        readOnlyHint: true,
+        destructiveHint: false,
+        // LLM sampling makes output non-deterministic - same input may produce different output.
+        idempotentHint: false,
+        openWorldHint: true,
+    },
 }, async (input) => {
     if (!input.url && !input.text) {
         return toolError({ type: "invalid_url", message: "One of url or text is required" });
     }
     return wrapHandler(() => rewriteForAeo(input, undefined, undefined, server));
 });
-// --- Tool 12: rewrite_for_geo ---
-server.tool("rewrite_for_geo", [
-    "Rewrite a content block for Generative Engine Optimization: entity-rich, comparison-ready, synthesis-friendly. Tuned for surfaces that summarize across sources (Perplexity, Google AI Mode, Claude search).",
-    "Read-only on input. Does NOT write back to the source URL - returns the rewritten content as a string.",
-    "This tool delegates the actual rewrite to the calling LLM via MCP sampling - it does not call any external API itself. The MCP host's model produces the rewrite. Output may vary across runs (model-dependent).",
-    "When to use: optimizing for synthesis-style answers across multiple sources. For direct-answer (BLUF + FAQ) optimization on a single page, use `rewrite_for_aeo` instead.",
-    "Either `url` or `text` must be provided. `target_query` is required.",
-].join("\n\n"), {
-    url: z
-        .string()
-        .url()
-        .optional()
-        .describe("Public URL whose content should be fetched and rewritten. Either this OR `text` is required."),
-    text: z
-        .string()
-        .optional()
-        .describe("Raw content to rewrite directly. Either this OR `url` is required."),
-    target_query: z
-        .string()
-        .describe("The user query the rewrite should answer. Required - drives entity selection and comparison framing."),
-    add_comparison_table: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe("If true, inject an explicit X-vs-Y comparison table into the rewrite (useful for `X vs Y` queries). Default false."),
-    max_words: z
-        .number()
-        .int()
-        .min(100)
-        .max(5000)
-        .optional()
-        .default(1500)
-        .describe("Soft word budget. Default 1500. Range 100-5000."),
-    respect_robots: z
-        .boolean()
-        .optional()
-        .default(true)
-        .describe("If true (default), respect robots.txt when fetching `url`. Ignored when `text` is used."),
+// --- rewrite.geo ---
+server.registerTool("rewrite.geo", {
+    title: "Rewrite for Generative Engine Optimization",
+    description: [
+        "Rewrite a content block for Generative Engine Optimization: entity-rich, comparison-ready, synthesis-friendly. Tuned for surfaces that summarize across sources (Perplexity, Google AI Mode, Claude search).",
+        "Read-only on input. Does NOT write back to the source URL - returns the rewritten content as a string.",
+        "This tool delegates the actual rewrite to the calling LLM via MCP sampling - it does not call any external API itself. The MCP host's model produces the rewrite. Output may vary across runs (model-dependent).",
+        "When to use: optimizing for synthesis-style answers across multiple sources. For direct-answer (BLUF + FAQ) optimization on a single page, use `rewrite.aeo` instead.",
+        "Either `url` or `text` must be provided. `target_query` is required.",
+    ].join("\n\n"),
+    inputSchema: {
+        url: z
+            .string()
+            .url()
+            .optional()
+            .describe("Public URL whose content should be fetched and rewritten. Either this OR `text` is required."),
+        text: z
+            .string()
+            .optional()
+            .describe("Raw content to rewrite directly. Either this OR `url` is required."),
+        target_query: z
+            .string()
+            .describe("The user query the rewrite should answer. Required - drives entity selection and comparison framing."),
+        add_comparison_table: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("If true, inject an explicit X-vs-Y comparison table into the rewrite (useful for `X vs Y` queries). Default false."),
+        max_words: z
+            .number()
+            .int()
+            .min(100)
+            .max(5000)
+            .optional()
+            .default(1500)
+            .describe("Soft word budget. Default 1500. Range 100-5000."),
+        respect_robots: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("If true (default), respect robots.txt when fetching `url`. Ignored when `text` is used."),
+    },
+    outputSchema: rewriteOutputShape,
+    annotations: {
+        title: "Rewrite for Generative Engine Optimization",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
 }, async (input) => {
     if (!input.url && !input.text) {
         return toolError({ type: "invalid_url", message: "One of url or text is required" });
     }
     return wrapHandler(() => rewriteForGeo(input, undefined, undefined, server));
 });
-// --- Tool 13: extract_entities ---
-server.tool("extract_entities", [
-    "Extract named entities, linked concepts, and sameAs graph nodes from a page's content and structured data. Combines body-text NER with JSON-LD `@type` / `sameAs` walking.",
-    "Read-only when given `url` (one HTTP GET). Zero network when given `text`.",
-    "Primary path: MCP sampling - the host LLM does the NER and returns typed entities with sameAs URIs. Fallback path: deterministic regex-based extractor when sampling is unavailable. The result includes `mode: \"sampling\" | \"regex_fallback\"` so callers can tell which path ran.",
-    "When to use: building an entity map for schema generation, or auditing whether a page's entities match its target topic. To validate the JSON-LD itself, use `audit_schema`.",
-    "Either `url` or `text` must be provided.",
-].join("\n\n"), {
-    url: z
-        .string()
-        .url()
-        .optional()
-        .describe("Public URL to fetch and analyze. Either this OR `text` is required."),
-    text: z
-        .string()
-        .optional()
-        .describe("Raw text/HTML to analyze directly. Either this OR `url` is required."),
-    respect_robots: z
-        .boolean()
-        .optional()
-        .default(true)
-        .describe("If true (default), respect robots.txt when fetching `url`. Ignored when `text` is used."),
-    render: z
-        .enum(["static", "headless"])
-        .optional()
-        .default("static")
-        .describe("Rendering mode for `url`. `static` (default) reads raw HTML. `headless` runs Playwright Chromium to capture JS-rendered content (adds 3-10s; requires `playwright-core` + `npx playwright install chromium`). Ignored when `text` is used."),
+// --- extract.entities ---
+server.registerTool("extract.entities", {
+    title: "Extract named entities and sameAs links",
+    description: [
+        "Extract named entities, linked concepts, and sameAs graph nodes from a page's content and structured data. Combines body-text NER with JSON-LD `@type` / `sameAs` walking.",
+        "Read-only when given `url` (one HTTP GET). Zero network when given `text`.",
+        "Primary path: MCP sampling - the host LLM does the NER and returns typed entities with sameAs URIs. Fallback path: deterministic regex-based extractor when sampling is unavailable. The result includes `mode: \"sampling\" | \"regex_fallback\"` so callers can tell which path ran.",
+        "When to use: building an entity map for schema generation, or auditing whether a page's entities match its target topic. To validate the JSON-LD itself, use `audit.schema`.",
+        "Either `url` or `text` must be provided.",
+    ].join("\n\n"),
+    inputSchema: {
+        url: z
+            .string()
+            .url()
+            .optional()
+            .describe("Public URL to fetch and analyze. Either this OR `text` is required."),
+        text: z
+            .string()
+            .optional()
+            .describe("Raw text/HTML to analyze directly. Either this OR `url` is required."),
+        respect_robots: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("If true (default), respect robots.txt when fetching `url`. Ignored when `text` is used."),
+        render: z
+            .enum(["static", "headless"])
+            .optional()
+            .default("static")
+            .describe("Rendering mode for `url`. `static` (default) reads raw HTML. `headless` runs Playwright Chromium to capture JS-rendered content (adds 3-10s; requires `playwright-core` + `npx playwright install chromium`). Ignored when `text` is used."),
+    },
+    outputSchema: extractEntitiesOutputShape,
+    annotations: {
+        title: "Extract named entities and sameAs links",
+        readOnlyHint: true,
+        destructiveHint: false,
+        // Sampling path is model-dependent; regex fallback is deterministic. Mark as non-idempotent to be safe.
+        idempotentHint: false,
+        openWorldHint: true,
+    },
 }, async (input) => {
     if (!input.url && !input.text) {
         return toolError({ type: "invalid_url", message: "One of url or text is required" });
     }
     return wrapHandler(() => extractEntities(input, undefined, undefined, server));
 });
-// --- Tool 14: test_citation ---
-server.tool("test_citation", [
-    "Simulate `would an AI engine cite this page for this query?`. The host LLM role-plays the chosen engine (chatgpt / claude / perplexity / google_ai_overviews / any), reads the page content, and returns a cite/no-cite verdict with the verbatim excerpt it would surface plus ranked improvements.",
-    "Read-only when given `url` (one HTTP GET). Zero network when given `text`.",
-    "Primary path uses MCP sampling. If the host doesn't support sampling, falls back to a deterministic heuristic derived from `score_citation_worthiness` (overall_score + per-engine subscore must both clear thresholds). The result includes `mode: \"sampling\" | \"static_heuristic\"` so callers can tell which path ran.",
-    "When to use: pre-publish gut-check for a specific query, or auditing whether existing content earns citation surface. Distinct from `score_citation_worthiness` (deterministic 0-100 score) and `audit_page` (whole-page rubric); this returns a binary cite/no-cite verdict tied to one query.",
-    "Either `url` or `text` must be provided. `target_query` is required.",
-].join("\n\n"), {
-    url: z
-        .string()
-        .url()
-        .optional()
-        .describe("Public URL to fetch and test. Either this OR `text` is required."),
-    text: z
-        .string()
-        .optional()
-        .describe("Raw text/HTML to test directly. Either this OR `url` is required."),
-    target_query: z
-        .string()
-        .min(3)
-        .describe("The user query the engine is answering. Required. Example: `how to add JSON-LD to a Next.js app`."),
-    engine: z
-        .enum(["chatgpt", "claude", "perplexity", "google_ai_overviews", "any"])
-        .optional()
-        .default("any")
-        .describe("Which engine to simulate. `any` (default) uses a generic AI-search persona. Specific engines tune the cite criteria (e.g. perplexity favors statistic-dense excerpts; google_ai_overviews favors schema + freshness)."),
-    respect_robots: z
-        .boolean()
-        .optional()
-        .default(true)
-        .describe("If true (default), respect robots.txt when fetching `url`. Ignored when `text` is used."),
+// --- score.test_citation ---
+server.registerTool("score.test_citation", {
+    title: "Test whether an AI engine would cite this page",
+    description: [
+        "Simulate `would an AI engine cite this page for this query?`. The host LLM role-plays the chosen engine (chatgpt / claude / perplexity / google_ai_overviews / any), reads the page content, and returns a cite/no-cite verdict with the verbatim excerpt it would surface plus ranked improvements.",
+        "Read-only when given `url` (one HTTP GET). Zero network when given `text`.",
+        "Primary path uses MCP sampling. If the host doesn't support sampling, falls back to a deterministic heuristic derived from `score.citation_worthiness` (overall_score + per-engine subscore must both clear thresholds). The result includes `mode: \"sampling\" | \"static_heuristic\"` so callers can tell which path ran.",
+        "When to use: pre-publish gut-check for a specific query, or auditing whether existing content earns citation surface. Distinct from `score.citation_worthiness` (deterministic 0-100 score) and `audit.page` (whole-page rubric); this returns a binary cite/no-cite verdict tied to one query.",
+        "Either `url` or `text` must be provided. `target_query` is required.",
+    ].join("\n\n"),
+    inputSchema: {
+        url: z
+            .string()
+            .url()
+            .optional()
+            .describe("Public URL to fetch and test. Either this OR `text` is required."),
+        text: z
+            .string()
+            .optional()
+            .describe("Raw text/HTML to test directly. Either this OR `url` is required."),
+        target_query: z
+            .string()
+            .min(3)
+            .describe("The user query the engine is answering. Required. Example: `how to add JSON-LD to a Next.js app`."),
+        engine: z
+            .enum(["chatgpt", "claude", "perplexity", "google_ai_overviews", "any"])
+            .optional()
+            .default("any")
+            .describe("Which engine to simulate. `any` (default) uses a generic AI-search persona. Specific engines tune the cite criteria (e.g. perplexity favors statistic-dense excerpts; google_ai_overviews favors schema + freshness)."),
+        respect_robots: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("If true (default), respect robots.txt when fetching `url`. Ignored when `text` is used."),
+    },
+    outputSchema: testCitationOutputShape,
+    annotations: {
+        title: "Test whether an AI engine would cite this page",
+        readOnlyHint: true,
+        destructiveHint: false,
+        // Sampling path is model-dependent.
+        idempotentHint: false,
+        openWorldHint: true,
+    },
 }, async (input) => {
     if (!input.url && !input.text) {
         return toolError({ type: "invalid_url", message: "One of url or text is required" });
     }
     return wrapHandler(() => testCitation(input, undefined, undefined, server));
 });
-// --- Tool 15: diff_pages ---
-server.tool("diff_pages", [
-    "Compare two URLs for AI citation-worthiness and return a structured breakdown of which page is more likely to be cited and why. Typical use: your page (url_a) vs a competitor's page (url_b).",
-    "Read-only. Runs audit_page on both URLs in parallel (2 HTTP fetches per URL), then diffs dimension_scores and findings. No new fetch logic beyond what audit_page already does.",
-    "Deterministic, rule-based; no LLM calls. Same two URLs return the same comparison on repeated runs.",
-    "When to use: competitive gap analysis - understand exactly which dimensions (schema, structure, robots, entity density, freshness, technical, authority, sitemap) put a competitor ahead, and get prioritized fix_recommendations_for_a to close the gap. For a single-URL audit, use audit_page. For overall scoring of one page, use score_citation_worthiness.",
-    "Capped at 2 URLs per call. Heuristic verdict - does not claim to know what AI assistants actually cite; verdict matches audit_page's existing rubric.",
-].join("\n\n"), diffPagesInputSchema.shape, async (input) => wrapHandler(() => diffPages(input)));
-// --- Tool 16: audit_site ---
-server.tool("audit_site", "Single-call site sweep: runs audit_page (homepage), check_robots, check_sitemap, and audit_schema in parallel and returns an overall grade plus top-5 fixes.", auditSiteInputSchema.shape, async (input) => wrapHandler(() => auditSite(input)));
-// --- Tool 17: audit_sitemap ---
-server.tool("audit_sitemap", [
-    "Site-wide content audit: discovers the sitemap, samples N URLs by deterministic uniform stride, runs audit_page on each, and returns score distribution + worst pages + most-common findings.",
-    "Read-only. One HTTP GET for sitemap discovery, optionally a few more for sitemap-index children, then `sample_size` × audit_page calls (each one HTTP GET + parsing). Polite throttling is enforced per host.",
-    "Deterministic — same domain + same sample_size returns the same set of URLs (uniform-stride sampling). Per-page scoring is rule-based; no LLM.",
-    "When to use: portfolio-level health check across a site (\"how does our content score on average?\"). Distinct from `audit_site` (homepage-only composite) and `check_sitemap` (validates sitemap.xml structure, not page content).",
-].join("\n\n"), auditSitemapInputSchema.shape, async (input) => wrapHandler(() => auditSitemap(input)));
-// --- Tool 18: save_audit_report ---
-server.tool("save_audit_report", "Render an audit_page or audit_site result as a Markdown report and write it to a file under MCP_WORKSPACE_ROOT (defaults to cwd).", saveAuditReportInputSchema.shape, async (input) => wrapHandler(() => saveAuditReport(input)));
+// --- diff.pages ---
+server.registerTool("diff.pages", {
+    title: "Diff two pages for citation-worthiness",
+    description: [
+        "Compare two URLs for AI citation-worthiness and return a structured breakdown of which page is more likely to be cited and why. Typical use: your page (url_a) vs a competitor's page (url_b).",
+        "Read-only. Runs audit.page on both URLs in parallel (2 HTTP fetches per URL), then diffs dimension_scores and findings. No new fetch logic beyond what audit.page already does.",
+        "Deterministic, rule-based; no LLM calls. Same two URLs return the same comparison on repeated runs.",
+        "When to use: competitive gap analysis - understand exactly which dimensions (schema, structure, robots, entity density, freshness, technical, authority, sitemap) put a competitor ahead, and get prioritized fix_recommendations_for_a to close the gap. For a single-URL audit, use audit.page. For overall scoring of one page, use score.citation_worthiness.",
+        "Capped at 2 URLs per call. Heuristic verdict - does not claim to know what AI assistants actually cite; verdict matches audit.page's existing rubric.",
+    ].join("\n\n"),
+    inputSchema: diffPagesInputSchema.shape,
+    outputSchema: diffPagesOutputShape,
+    annotations: {
+        title: "Diff two pages for citation-worthiness",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+}, async (input) => wrapHandler(() => diffPages(input)));
+// --- audit.site ---
+server.registerTool("audit.site", {
+    title: "Audit site (homepage + robots + sitemap + schema)",
+    description: "Single-call site sweep: runs audit.page (homepage), check.robots, check.sitemap, and audit.schema in parallel and returns an overall grade plus top-5 fixes.",
+    inputSchema: auditSiteInputSchema.shape,
+    outputSchema: auditSiteOutputShape,
+    annotations: {
+        title: "Audit site (homepage + robots + sitemap + schema)",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+}, async (input) => wrapHandler(() => auditSite(input)));
+// --- audit.sitemap ---
+server.registerTool("audit.sitemap", {
+    title: "Audit a site's content by sampling its sitemap",
+    description: [
+        "Site-wide content audit: discovers the sitemap, samples N URLs by deterministic uniform stride, runs audit.page on each, and returns score distribution + worst pages + most-common findings.",
+        "Read-only. One HTTP GET for sitemap discovery, optionally a few more for sitemap-index children, then `sample_size` × audit.page calls (each one HTTP GET + parsing). Polite throttling is enforced per host.",
+        "Deterministic — same domain + same sample_size returns the same set of URLs (uniform-stride sampling). Per-page scoring is rule-based; no LLM.",
+        "When to use: portfolio-level health check across a site (\"how does our content score on average?\"). Distinct from `audit.site` (homepage-only composite) and `check.sitemap` (validates sitemap.xml structure, not page content).",
+    ].join("\n\n"),
+    inputSchema: auditSitemapInputSchema.shape,
+    outputSchema: auditSitemapOutputShape,
+    annotations: {
+        title: "Audit a site's content by sampling its sitemap",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+}, async (input) => wrapHandler(() => auditSitemap(input)));
+// --- report.save ---
+server.registerTool("report.save", {
+    title: "Save audit report to disk",
+    description: "Render an audit.page or audit.site result as a Markdown report and write it to a file under MCP_WORKSPACE_ROOT (defaults to cwd).",
+    inputSchema: saveAuditReportInputSchema.shape,
+    outputSchema: saveReportOutputShape,
+    annotations: {
+        title: "Save audit report to disk",
+        // Writes a file - not read-only.
+        readOnlyHint: false,
+        // Overwrite=true (default) replaces existing files; the change is recoverable but writes do occur.
+        destructiveHint: true,
+        // Same input writes the same content to the same path.
+        idempotentHint: true,
+        // Operates on the local filesystem only.
+        openWorldHint: false,
+    },
+}, async (input) => wrapHandler(() => saveAuditReport(input)));
 // --- Prompts: one-click entry points for AI-SEO workflows ---
 // Surfaced by hosts like Claude Desktop as suggested actions. Lowers activation cost
 // vs. asking users to pick among the 16-tool catalog.
@@ -372,9 +614,9 @@ server.prompt("audit_my_homepage", "Run a full AI-SEO audit of a site's homepage
             role: "user",
             content: {
                 type: "text",
-                text: `Call the \`audit_site\` tool with domain="${domain}" and respect_robots=true. ` +
+                text: `Call the \`audit.site\` tool with domain="${domain}" and respect_robots=true. ` +
                     `When the result returns, summarize the overall_grade, the top_5_fixes (highest-impact first), ` +
-                    `and the content_quality from the underlying audit_page. Recommend the single most leveraged fix first.`,
+                    `and the content_quality from the underlying audit.page. Recommend the single most leveraged fix first.`,
             },
         },
     ],
@@ -385,7 +627,7 @@ server.prompt("find_citation_blockers", "Audit a URL and surface only the critic
             role: "user",
             content: {
                 type: "text",
-                text: `Call \`audit_page\` with url="${url}" and respect_robots=true. ` +
+                text: `Call \`audit.page\` with url="${url}" and respect_robots=true. ` +
                     `From the result, filter findings to severity="critical" only. ` +
                     `Group them by category and present a prioritized fix list. ` +
                     `Ignore warnings and info-level findings for this pass.`,
@@ -399,7 +641,7 @@ server.prompt("generate_llms_txt_for_domain", "Generate a valid llms.txt for a d
             role: "user",
             content: {
                 type: "text",
-                text: `Call \`generate_llms_txt\` with domain="${domain}", max_pages=50, include_full=false. ` +
+                text: `Call \`llms_txt.generate\` with domain="${domain}", max_pages=50, include_full=false. ` +
                     `Return the generated llms.txt verbatim in a code block, then summarize how many pages were indexed.`,
             },
         },
@@ -411,7 +653,7 @@ server.prompt("check_ai_crawler_access", "Report which AI training and search cr
             role: "user",
             content: {
                 type: "text",
-                text: `Call \`check_robots\` with domain="${domain}". ` +
+                text: `Call \`check.robots\` with domain="${domain}". ` +
                     `From the result, build a table grouped by training_crawlers / search_crawlers / user_triggered, ` +
                     `with one row per crawler and an allowed/blocked verdict. ` +
                     `Highlight any AI search crawlers that are blocked - those silently kill citation surface.`,
@@ -428,7 +670,7 @@ server.prompt("score_my_citation_worthiness", "Score how citable a URL is for AI
             role: "user",
             content: {
                 type: "text",
-                text: `Call \`score_citation_worthiness\` with url="${url}", target_query="${target_query}", respect_robots=true. ` +
+                text: `Call \`score.citation_worthiness\` with url="${url}", target_query="${target_query}", respect_robots=true. ` +
                     `Present overall_score and per-engine scores (Perplexity, ChatGPT, Google AI Overviews, Claude). ` +
                     `Then suggest the 3 most impactful structural changes (BLUF opening, FAQ blocks, entity density) to lift the lowest score.`,
             },
@@ -484,7 +726,7 @@ robots.txt allows OAI-SearchBot, PerplexityBot, Claude-SearchBot. Blocking train
 ## 13. Sitemap freshness
 XML sitemap present, lastmod >80% coverage, listed in robots.txt.
 
-Use \`audit_page\` to score a URL across all 13 signals at once.
+Use \`audit.page\` to score a URL across all 13 signals at once.
 `;
 const CRAWLERS_DOC = `# AI crawlers reference
 
@@ -538,7 +780,7 @@ Allow: /
 \`\`\`
 (Blocks training, allows everything else - including search crawlers.)
 
-Use \`check_robots\` to see your current posture per crawler.
+Use \`check.robots\` to see your current posture per crawler.
 `;
 server.resource("ai-citation-signals", "ai-citation://signals", { mimeType: "text/markdown", description: "The 13 signals AI assistants use to decide what to cite, with examples." }, async (uri) => ({
     contents: [{ uri: uri.href, mimeType: "text/markdown", text: SIGNALS_DOC }],