@gravitykit/block-mcp 2.0.0-beta → 2.1.0

package/src/tools/write.ts

@@ -9,8 +9,9 @@
  */
 
 import type { WordPressBlockClient } from '../client.js';
-import { formatPreferenceWarning } from '../preferences.js';
+import { formatPreferenceWarning, withFormattedWarnings } from '../preferences.js';
 import { enrichBlock, enrichBlocks, type BlockDef } from '../enrichers.js';
+import { coercePostId } from '../coerce.js';
 
 /** Shape shared by every block-input arg in this module. */
 export const BLOCK_INPUT_SCHEMA = {
@@ -75,7 +76,9 @@ export const WRITE_TOOLS = [
     // idempotentHint is false: every call creates a new revision, and
     // revision history is observable to other readers. Same-input/same-state
     // is true at the block level but not at the post level.
-    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true, title: 'Update one block' },
+    // destructiveHint is true: attributes/innerHTML overwrite the block's
+    // existing content rather than merging additively.
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true, title: 'Update one block' },
     outputSchema: {
       type: 'object',
       properties: {
@@ -123,7 +126,8 @@ export const WRITE_TOOLS = [
     name: 'update_blocks',
     description:
       'Update N independent blocks atomically in ONE revision. Each item targets one block by `ref` (recommended) or `flat_index`, with `attributes` and/or `innerHTML`. Validation is all-or-nothing: any stale ref / out-of-range index / dual-storage rejection / duplicate target aborts the batch with itemized errors — no partial writes hit disk. Max 50 items per call. Counts as ONE write against the per-post rate limit. Use this instead of looping update_block when fixing multiple blocks on the same post — keeps revision history clean. Pass `verbose: true` to include `saved.inner_html` + `saved.attributes` per result for per-item verification without a re-read.',
-    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true, title: 'Batch-update blocks' },
+    // destructiveHint is true: same overwrite semantics as update_block, applied per item.
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true, title: 'Batch-update blocks' },
     outputSchema: {
       type: 'object',
       properties: {
@@ -192,7 +196,13 @@ export const WRITE_TOOLS = [
   {
     name: 'insert_blocks',
     description:
-      'Insert blocks at a top-level position. Anchoring options (use one): `after_ref`/`before_ref` (stable gk_ref — recommended), or `after_top_level`/`before_top_level` (top_level_counter). Omit anchors or set after_top_level:-1 to append; "start" prepends. Legacy-tier blocks rejected per the site policy. Blocks whose attribute schema is HTML-sourced (e.g. core/paragraph `content`, core/image `url`) must include `innerHTML` matching the attribute(s) — attribute-only inserts are rejected with `inner_html_required` to prevent the self-closing-block / "invalid content" failure mode. Response.inserted[] carries `ref`, `path`, and `top_level_counter` so you can chain edit_block_tree without re-reading.',
+      'Insert top-level blocks into a post.\n\n' +
+      'POSITIONING — use exactly ONE anchor (any other key, e.g. `after`, `before`, `position`, is rejected):\n' +
+      '- `before_ref` / `after_ref` — gk_ref from get_page_blocks. Recommended: refs survive sibling shifts.\n' +
+      '- `before_top_level` / `after_top_level` — top_level_counter position.\n' +
+      '- Prepend at the very top: `before_top_level: 0`. Append at the end: omit all anchors.\n\n' +
+      'CONTENT — legacy-tier blocks are rejected per the site policy. Blocks with HTML-sourced attributes (e.g. core/paragraph `content`, core/image `url`) must include matching `innerHTML`; attribute-only inserts fail with `inner_html_required`.\n\n' +
+      'VERIFY — the response\'s inserted[] returns `ref`, `path`, and `top_level_counter`: confirm the block landed where you intended before moving on. The refs let you chain edit_block_tree without re-reading.',
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true, title: 'Insert blocks' },
     outputSchema: INSERTED_REFS_SCHEMA,
     inputSchema: {
@@ -201,7 +211,7 @@ export const WRITE_TOOLS = [
         post_id: { type: 'number', description: 'Post ID.' },
         after_top_level: {
           type: ['number', 'string'],
-          description: 'top_level_counter to insert AFTER. -1/omit = append, "start" = prepend.',
+          description: 'top_level_counter to insert AFTER (omit or -1 = append). To prepend at the very top, prefer `before_top_level: 0`.',
         },
         before_top_level: {
           type: 'number',
@@ -217,7 +227,7 @@ export const WRITE_TOOLS = [
         },
         blocks: {
           type: 'array',
-          description: 'Blocks to insert.',
+          description: 'Blocks to insert. Each def nests recursively via `innerBlocks` — build a whole container (group/columns/callout) with its children in this one call; give the container its empty wrapper `innerHTML` (e.g. \'<div class="wp-block-group"></div>\').',
           items: BLOCK_INPUT_SCHEMA,
         },
       },
@@ -260,7 +270,7 @@ export const WRITE_TOOLS = [
         post_id: { type: 'number', description: 'Post ID.' },
         start: { type: 'number', description: 'top_level_counter of first block to replace.' },
         count: { type: 'number', description: 'How many top-level blocks to remove. Pass 0 to insert without removing.' },
-        blocks: { type: 'array', description: 'Replacement blocks. May be empty (pure delete) or any length.', items: BLOCK_INPUT_SCHEMA },
+        blocks: { type: 'array', description: 'Replacement blocks. May be empty (pure delete) or any length. Each def nests recursively via `innerBlocks` for containers (group/columns/callout) — give the container its empty wrapper `innerHTML`.', items: BLOCK_INPUT_SCHEMA },
       },
       required: ['post_id', 'start', 'count', 'blocks'],
     },
@@ -297,7 +307,7 @@ export const WRITE_TOOLS = [
       type: 'object' as const,
       properties: {
         post_id: { type: 'number', description: 'Post ID.' },
-        blocks: { type: 'array', description: 'Complete blocks array (replaces all).', items: BLOCK_INPUT_SCHEMA },
+        blocks: { type: 'array', description: 'Complete blocks array (replaces all). Each def nests recursively via `innerBlocks` for containers (group/columns/callout) — give the container its empty wrapper `innerHTML`.', items: BLOCK_INPUT_SCHEMA },
       },
       required: ['post_id', 'blocks'],
     },
@@ -327,14 +337,14 @@ export async function handleWriteTool(
 ): Promise<unknown> {
   switch (toolName) {
     case 'update_block': {
-      const postId = args.post_id as number;
+      const postId = coercePostId(args.post_id, 'update_block');
       const flatIndex = args.flat_index as number | undefined;
       const ref = args.ref as string | undefined;
       const blockName = args.block_name as string | undefined;
       let attributes = args.attributes as Record<string, unknown> | undefined;
       let innerHTML = args.innerHTML as string | undefined;
 
-      if (postId === undefined || postId === null) throw new Error('post_id is required');
+      if (postId === undefined) throw new Error('post_id is required');
       const hasIndex = typeof flatIndex === 'number' && Number.isFinite(flatIndex) && flatIndex >= 0;
       const hasRef = typeof ref === 'string' && ref.length > 0;
       if (!hasIndex && !hasRef) {
@@ -363,7 +373,7 @@ export async function handleWriteTool(
     }
 
     case 'update_blocks': {
-      const postId = args.post_id as number;
+      const postId = coercePostId(args.post_id, 'update_blocks');
       const updates = args.updates as Array<{
         ref?: string;
         flat_index?: number;
@@ -372,7 +382,7 @@ export async function handleWriteTool(
         innerHTML?: string;
       }> | undefined;
 
-      if (postId === undefined || postId === null) throw new Error('post_id is required');
+      if (postId === undefined) throw new Error('post_id is required');
       if (!Array.isArray(updates) || updates.length === 0) {
         throw new Error('updates must be a non-empty array');
       }
@@ -434,7 +444,7 @@ export async function handleWriteTool(
     }
 
     case 'insert_blocks': {
-      const postId = args.post_id as number;
+      const postId = coercePostId(args.post_id, 'insert_blocks');
       const after = args.after_top_level as number | 'start' | undefined;
       const before = args.before_top_level as number | undefined;
       const afterRef = args.after_ref as string | undefined;
@@ -445,7 +455,7 @@ export async function handleWriteTool(
         innerHTML?: string;
       }>;
 
-      if (postId === undefined || postId === null) throw new Error('post_id is required');
+      if (postId === undefined) throw new Error('post_id is required');
       if (!blocks || blocks.length === 0) throw new Error('At least one block is required in the blocks array');
 
       const result = await client.insertBlocks(postId, {
@@ -455,19 +465,16 @@ export async function handleWriteTool(
         ...(beforeRef ? { before_ref: beforeRef } : {}),
         blocks: await enrichBlocks(blocks as BlockDef[]),
       });
-      if (result.warnings && result.warnings.length > 0) {
-        return { ...result, formatted_warnings: result.warnings.map(formatPreferenceWarning) };
-      }
-      return result;
+      return withFormattedWarnings(result, formatPreferenceWarning);
     }
 
     case 'delete_block': {
-      const postId = args.post_id as number;
+      const postId = coercePostId(args.post_id, 'delete_block');
       const topLevelCounter = args.top_level_counter as number | undefined;
       const ref = args.ref as string | undefined;
       const count = args.count as number | undefined;
 
-      if (postId === undefined || postId === null) throw new Error('post_id is required');
+      if (postId === undefined) throw new Error('post_id is required');
       const hasCounter = typeof topLevelCounter === 'number' && Number.isFinite(topLevelCounter) && topLevelCounter >= 0;
       const hasRef = typeof ref === 'string' && ref.length > 0;
       if (!hasCounter && !hasRef) {
@@ -489,7 +496,7 @@ export async function handleWriteTool(
     }
 
     case 'replace_block_range': {
-      const postId = args.post_id as number;
+      const postId = coercePostId(args.post_id, 'replace_block_range');
       const start = args.start as number;
       const count = args.count as number;
       const blocks = args.blocks as Array<{
@@ -498,40 +505,34 @@ export async function handleWriteTool(
         innerHTML?: string;
       }>;
 
-      if (postId === undefined || postId === null) throw new Error('post_id is required');
-      if (typeof start !== 'number' || start < 0) throw new Error('start must be a non-negative integer');
-      if (typeof count !== 'number' || count < 0) throw new Error('count must be a non-negative integer');
+      if (postId === undefined) throw new Error('post_id is required');
+      if (!Number.isSafeInteger(start) || start < 0) throw new Error('start must be a non-negative integer');
+      if (!Number.isSafeInteger(count) || count < 0) throw new Error('count must be a non-negative integer');
       if (!Array.isArray(blocks)) throw new Error('blocks must be an array (may be empty for a pure delete)');
 
       const result = await client.replaceBlocksRange(postId, { start, count, blocks: await enrichBlocks(blocks as BlockDef[]) });
-      if (result.warnings && result.warnings.length > 0) {
-        return { ...result, formatted_warnings: result.warnings.map(formatPreferenceWarning) };
-      }
-      return result;
+      return withFormattedWarnings(result, formatPreferenceWarning);
     }
 
     case 'rewrite_post_blocks': {
-      const postId = args.post_id as number;
+      const postId = coercePostId(args.post_id, 'rewrite_post_blocks');
       const blocks = args.blocks as Array<{
         name: string;
         attributes?: Record<string, unknown>;
         innerHTML?: string;
       }>;
 
-      if (postId === undefined || postId === null) throw new Error('post_id is required');
+      if (postId === undefined) throw new Error('post_id is required');
       if (!blocks || blocks.length === 0) throw new Error('At least one block is required for a full page rewrite');
 
       const result = await client.replaceAllBlocks(postId, await enrichBlocks(blocks as BlockDef[]));
-      if (result.warnings && result.warnings.length > 0) {
-        return { ...result, formatted_warnings: result.warnings.map(formatPreferenceWarning) };
-      }
-      return result;
+      return withFormattedWarnings(result, formatPreferenceWarning);
     }
 
     case 'revert_to_revision': {
-      const postId = args.post_id as number;
+      const postId = coercePostId(args.post_id, 'revert_to_revision');
       const revisionId = args.revision_id as number;
-      if (postId === undefined || postId === null) throw new Error('post_id is required');
+      if (postId === undefined) throw new Error('post_id is required');
       if (revisionId === undefined || revisionId === null) throw new Error('revision_id is required');
       return await client.revertToRevision(postId, revisionId);
     }

package/src/tools/yoast.ts

@@ -11,27 +11,24 @@
  */
 
 import type { WordPressBlockClient } from '../client.js';
-import type {
-  YoastSchemaPageType,
-  YoastSchemaArticleType,
-  YoastRobotsAdvanced,
-  YoastUpdateRequest,
-  YoastBulkUpdateItem,
+import { coercePostId } from '../coerce.js';
+import {
+  YOAST_SCHEMA_PAGE_TYPES,
+  YOAST_SCHEMA_ARTICLE_TYPES,
+  YOAST_ROBOTS_ADVANCED,
+  type YoastSchemaPageType,
+  type YoastSchemaArticleType,
+  type YoastRobotsAdvanced,
+  type YoastUpdateRequest,
+  type YoastBulkUpdateItem,
 } from '../types.js';
 
-const SCHEMA_PAGE_TYPES: YoastSchemaPageType[] = [
-  'WebPage', 'ItemPage', 'AboutPage', 'FAQPage', 'QAPage',
-  'ProfilePage', 'ContactPage', 'MedicalWebPage', 'CollectionPage',
-  'CheckoutPage', 'RealEstateListing', 'SearchResultsPage',
-];
-
-const SCHEMA_ARTICLE_TYPES: YoastSchemaArticleType[] = [
-  'Article', 'BlogPosting', 'SocialMediaPosting', 'NewsArticle',
-  'AdvertiserContentArticle', 'SatiricalArticle', 'ScholarlyArticle',
-  'TechArticle', 'Report', 'None',
-];
-
-const ROBOTS_ADVANCED: YoastRobotsAdvanced[] = ['noimageindex', 'noarchive', 'nosnippet'];
+// Local aliases: the enum values themselves live in types.ts (single source
+// shared with the TS union types); these names keep the rest of this file
+// unchanged.
+const SCHEMA_PAGE_TYPES = YOAST_SCHEMA_PAGE_TYPES;
+const SCHEMA_ARTICLE_TYPES = YOAST_SCHEMA_ARTICLE_TYPES;
+const ROBOTS_ADVANCED = YOAST_ROBOTS_ADVANCED;
 
 /** Field-level schema reused by yoast_update_seo and yoast_bulk_update_seo. */
 const YOAST_FIELD_PROPERTIES = {
@@ -40,8 +37,8 @@ const YOAST_FIELD_PROPERTIES = {
   canonical: { type: 'string', description: 'Canonical URL override.' },
   focus_keyword: { type: 'string', description: 'Focus keyphrase.' },
   noindex: {
-    type: ['boolean', 'null'],
-    description: 'Tri-state: true=noindex, false=explicit index, null=post-type default.',
+    type: 'boolean',
+    description: 'true=noindex, false=explicit index. Pass null to reset to the post-type default; omit to leave the current value unchanged. (Advertised as a single boolean type because some AI clients — e.g. Google Gemini — reject a "null" member in a type array; the handler still accepts an explicit null.)',
   },
   nofollow: { type: 'boolean', description: 'true=nofollow, false=follow.' },
   robots_advanced: {
@@ -132,17 +129,17 @@ export async function handleYoastTool(
 ): Promise<unknown> {
   switch (toolName) {
     case 'yoast_get_seo': {
-      const postId = args.post_id;
-      if (typeof postId !== 'number') {
-        throw new Error('yoast_get_seo: "post_id" (number) is required');
+      const postId = coercePostId(args.post_id, 'yoast_get_seo');
+      if (postId === undefined) {
+        throw new Error('yoast_get_seo: "post_id" is required');
       }
       return client.getYoastSEO(postId);
     }
 
     case 'yoast_update_seo': {
-      const postId = args.post_id;
-      if (typeof postId !== 'number') {
-        throw new Error('yoast_update_seo: "post_id" (number) is required');
+      const postId = coercePostId(args.post_id, 'yoast_update_seo');
+      if (postId === undefined) {
+        throw new Error('yoast_update_seo: "post_id" is required');
       }
       const { post_id: _omit, ...rest } = args;
       void _omit;
@@ -163,11 +160,13 @@ export async function handleYoastTool(
           throw new Error('yoast_bulk_update_seo: each item in `posts` must be an object');
         }
         const obj = raw as Record<string, unknown>;
-        if (typeof obj.post_id !== 'number') {
-          throw new Error('yoast_bulk_update_seo: each item requires `post_id` (number)');
+        const id = coercePostId(obj.post_id, 'yoast_bulk_update_seo');
+        if (id === undefined) {
+          throw new Error('yoast_bulk_update_seo: each item requires `post_id`');
         }
-        const { post_id: id, ...rest } = obj;
-        items.push({ post_id: id as number, ...narrowYoastFields(rest) });
+        const { post_id: _omit, ...rest } = obj;
+        void _omit;
+        items.push({ post_id: id, ...narrowYoastFields(rest) });
       }
       return client.bulkUpdateYoastSEO(items);
     }

package/src/types.ts

@@ -83,8 +83,8 @@ export interface BlockType {
 export interface PatternPreference {
   /** Computed preference score */
   score: number;
-  /** Human-readable tier */
-  tier: 'recommended' | 'acceptable' | 'avoid' | 'legacy';
+  /** Human-readable tier (matches the server: preferred/acceptable/avoid/legacy) */
+  tier: 'preferred' | 'acceptable' | 'avoid' | 'legacy';
   /** Reasons contributing to the score */
   reasons: string[];
 }
@@ -275,8 +275,12 @@ export interface BlockWriteResponse {
 /** Response from block delete (DELETE) operations. */
 export interface BlockDeleteResponse {
   success: boolean;
+  /** Flat index of the first removed block */
+  deleted_index: number;
   /** Number of blocks removed */
-  removed: number;
+  deleted_count: number;
+  /** Non-fatal warnings emitted by the delete */
+  warnings: unknown[];
   /** WordPress revision ID of the pre-edit snapshot */
   before_revision_id: number;
   /** WordPress revision ID of the post-edit state */
@@ -566,16 +570,8 @@ export interface MutationRequest {
   ref?: string;
   attributes?: Record<string, unknown>;
   innerHTML?: string;
-  block?: {
-    name: string;
-    attributes?: Record<string, unknown>;
-    innerHTML?: string;
-    innerBlocks?: Array<{
-      name: string;
-      attributes?: Record<string, unknown>;
-      innerHTML?: string;
-    }>;
-  };
+  /** replace-block / insert-child payload. Nests recursively via innerBlocks. */
+  block?: BlockInput;
   wrapper?: {
     name?: string;
     attributes?: Record<string, unknown>;
@@ -584,12 +580,10 @@ export interface MutationRequest {
   destination?: number[];
   /** Alternative to `destination` — resolve from a ref instead of a path. */
   destination_ref?: string;
-  /** Alias for destination — path of block to insert BEFORE (pre-move indexing). */
-  before?: number[];
-  /** Alternative to `before` — resolve from a ref instead of a path. */
-  before_ref?: string;
   /** Number of consecutive blocks to move/operate on. Default: 1. */
   count?: number;
+  /** Preview the mutation without writing. */
+  dry_run?: boolean;
 }
 
 /** Warning about static block markup staleness. */
@@ -622,7 +616,11 @@ export interface MutationResponse {
 // v1.2 — Docs Lifecycle: Posts
 // ============================================
 
-/** A block in structured form, suitable for create_post's `blocks` input. */
+/**
+ * A block in structured form — the def shape accepted by every write that
+ * creates blocks (create_post `blocks`, insert_blocks, replace ranges/all,
+ * mutate replace-block / insert-child). Nests recursively via `innerBlocks`.
+ */
 export interface BlockInput {
   name: string;
   attributes?: Record<string, unknown>;
@@ -631,6 +629,12 @@ export interface BlockInput {
   innerContent?: unknown[];
 }
 
+/** Partial-update payload for a single existing block (update_block / by-ref / batch items). */
+export interface BlockPatch {
+  attributes?: Record<string, unknown>;
+  innerHTML?: string;
+}
+
 export type CreatePostStatus = 'draft' | 'pending' | 'private' | 'publish' | 'future';
 export type UpdatePostStatus = CreatePostStatus | 'trash';
 export type CommentPingStatus = 'open' | 'closed';
@@ -795,17 +799,27 @@ export interface UploadMediaResponse {
 // Routes only register when Yoast SEO is active on the target site.
 // ============================================
 
-export type YoastSchemaPageType =
-  | 'WebPage' | 'ItemPage' | 'AboutPage' | 'FAQPage' | 'QAPage'
-  | 'ProfilePage' | 'ContactPage' | 'MedicalWebPage' | 'CollectionPage'
-  | 'CheckoutPage' | 'RealEstateListing' | 'SearchResultsPage';
-
-export type YoastSchemaArticleType =
-  | 'Article' | 'BlogPosting' | 'SocialMediaPosting' | 'NewsArticle'
-  | 'AdvertiserContentArticle' | 'SatiricalArticle' | 'ScholarlyArticle'
-  | 'TechArticle' | 'Report' | 'None';
-
-export type YoastRobotsAdvanced = 'noimageindex' | 'noarchive' | 'nosnippet';
+/**
+ * Single source of truth for the Yoast schema-page-type enum — the const
+ * array backs both the runtime value (JSON Schema `enum`, narrowing filters
+ * in src/tools/yoast.ts) and the TS union type below, so the two can't drift.
+ */
+export const YOAST_SCHEMA_PAGE_TYPES = [
+  'WebPage', 'ItemPage', 'AboutPage', 'FAQPage', 'QAPage',
+  'ProfilePage', 'ContactPage', 'MedicalWebPage', 'CollectionPage',
+  'CheckoutPage', 'RealEstateListing', 'SearchResultsPage',
+] as const;
+export type YoastSchemaPageType = typeof YOAST_SCHEMA_PAGE_TYPES[number];
+
+export const YOAST_SCHEMA_ARTICLE_TYPES = [
+  'Article', 'BlogPosting', 'SocialMediaPosting', 'NewsArticle',
+  'AdvertiserContentArticle', 'SatiricalArticle', 'ScholarlyArticle',
+  'TechArticle', 'Report', 'None',
+] as const;
+export type YoastSchemaArticleType = typeof YOAST_SCHEMA_ARTICLE_TYPES[number];
+
+export const YOAST_ROBOTS_ADVANCED = ['noimageindex', 'noarchive', 'nosnippet'] as const;
+export type YoastRobotsAdvanced = typeof YOAST_ROBOTS_ADVANCED[number];
 
 /**
  * Writable Yoast SEO fields. All optional in update payloads — only the
@@ -857,6 +871,6 @@ export interface YoastBulkUpdateItem extends YoastSEOFields {
 }
 
 export type YoastBulkUpdateResponse = Array<
-  | { post_id: number; success: true; seo: YoastSEOMeta }
-  | { post_id: number; success: false; error: string }
+  | YoastSEOMeta
+  | { post_id?: number; error: string }
 >;

package/src/validate-args.ts

@@ -0,0 +1,109 @@
+/**
+ * Tool-argument validation for the MCP dispatch.
+ *
+ * The MCP SDK does not validate CallTool arguments against a tool's
+ * `inputSchema`, so a misnamed parameter (e.g. `after` instead of
+ * `after_top_level`) was silently dropped and the handler ran with its
+ * defaults — turning a positioning mistake into a wrong-but-"successful" write.
+ *
+ * This rejects unknown top-level keys loudly — naming the valid ones with a
+ * "did you mean" suggestion — and flags missing required keys, before the
+ * handler runs.
+ */
+
+interface InputSchema {
+  properties?: Record<string, unknown>;
+  required?: string[];
+  additionalProperties?: unknown;
+}
+
+/**
+ * Throw a descriptive Error if `args` carries keys the tool doesn't declare, or
+ * omits a required key. No-op when the tool has no schema, or when the schema
+ * explicitly opts into additional properties.
+ */
+export function validateToolArgs(
+  toolName: string,
+  inputSchema: InputSchema | undefined,
+  args: Record<string, unknown>,
+): void {
+  const properties = inputSchema?.properties;
+  if (!properties) {
+    return; // No declared shape — nothing to validate against.
+  }
+
+  const known = Object.keys(properties);
+  const provided = Object.keys(args ?? {});
+
+  // Respect an explicit opt-in to extra props (a map-shaped schema sets
+  // `additionalProperties` to a schema object rather than leaving it absent).
+  const allowsExtra =
+    inputSchema?.additionalProperties !== undefined && inputSchema.additionalProperties !== false;
+
+  if (!allowsExtra) {
+    const unknown = provided.filter((k) => !known.includes(k));
+    if (unknown.length > 0) {
+      const parts = unknown.map((k) => {
+        const near = closestKey(k, known);
+        return near ? `'${k}' (did you mean '${near}'?)` : `'${k}'`;
+      });
+      throw new Error(
+        `Unknown parameter(s) for ${toolName}: ${parts.join(', ')}. ` +
+          `Valid parameters: ${known.join(', ')}.`,
+      );
+    }
+  }
+
+  const required = inputSchema?.required ?? [];
+  const missing = required.filter((r) => !(r in (args ?? {})));
+  if (missing.length > 0) {
+    throw new Error(`Missing required parameter(s) for ${toolName}: ${missing.join(', ')}.`);
+  }
+}
+
+/**
+ * Best-effort suggestion for a mistyped key. Prefers a known key that shares a
+ * prefix/substring with the input — the common agent mistake is a shortened
+ * name like `after` for `after_top_level` — then falls back to edit distance.
+ */
+function closestKey(input: string, candidates: string[]): string | null {
+  const lc = input.toLowerCase();
+  const affixed = candidates
+    .filter((c) => {
+      const cl = c.toLowerCase();
+      return cl.startsWith(lc) || lc.startsWith(cl) || cl.includes(lc) || lc.includes(cl);
+    })
+    .sort((a, b) => a.length - b.length);
+  if (affixed.length > 0) {
+    return affixed[0];
+  }
+
+  let best: string | null = null;
+  let bestDist = Infinity;
+  for (const c of candidates) {
+    const d = levenshtein(lc, c.toLowerCase());
+    if (d < bestDist) {
+      bestDist = d;
+      best = c;
+    }
+  }
+  return best !== null && bestDist <= Math.max(2, Math.ceil(input.length / 2)) ? best : null;
+}
+
+function levenshtein(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  let prev = Array.from({ length: n + 1 }, (_, i) => i);
+  let curr = new Array<number>(n + 1);
+  for (let i = 1; i <= m; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[n];
+}