@wowok/agent-mcp 2.6.1 → 2.6.4

package/dist/tools/index.js

@@ -33,7 +33,7 @@ export const TOOL_REGISTRY = [
         handler: handleOnchainOperations,
         config: {
             title: "⛓️ On-chain Operations",
-            description: "On-chain operations for WoWok object: service (marketplace listings), machine (workflow templates), progress (order tracking), repository (on-chain database), arbitration (dispute resolution), contact (IM management), treasury (team funds), reward (incentive pools), allocation (auto-distribution), permission (access control), guard (programmable trust rules), personal (public profile), payment (direct coin transfers), demand (service requests), order (order management), gen_passport (verified credentials), proof (on-chain proof objects), gen_proof (generate proof shortcut).\n\n📌 Project association: Pass env.project='<prefix>' to auto-tag the object on-chain AND auto-associate it to the SQLite project (created objects are automatically added). For complex builds, create a project first (project_operation action='create_project'). For single objects, just pass env.project. See PROJECT ASSOCIATION POLICY in system prompt.\n\n💡 Schema hint: Use schema_query with action='get' and name='onchain_operations' to retrieve the complete parameter schema. For individual operation schemas (e.g., 'onchain_operations_permission'), use schema_query with action='list_operations' to see all available operation schemas.",
+            description: "On-chain operations for WoWok object: service (marketplace listings), machine (workflow templates), progress (order tracking), repository (on-chain database), arbitration (dispute resolution), contact (IM management), treasury (team funds), reward (incentive pools), allocation (auto-distribution), permission (access control), guard (programmable trust rules), personal (public profile), payment (direct coin transfers), demand (service requests), order (order management), gen_passport (verified credentials), proof (on-chain proof objects), gen_proof (generate proof shortcut).\n\n💰 FUND SAFETY (service/arbitration/treasury/reward/allocation/payment): amounts are parsed against the target object's IMMUTABLE generic token type (e.g. Treasury<USDT> accepts ONLY USDT — mismatched coins/token_types are BLOCKED before execution). Monetary input with unresolvable token precision is BLOCKED (never guesses decimals) with known-token suggestions; retry once the token info resolves. Display-format amounts like \"2WOW\" are converted to raw u64 using the token's own decimals.\n\n📌 Project association: Pass env.project='<prefix>' to auto-tag the object on-chain AND auto-associate it to the SQLite project (created objects are automatically added). For complex builds, create a project first (project_operation action='create_project'). For single objects, just pass env.project. See PROJECT ASSOCIATION POLICY in system prompt.\n\n💡 Schema hint: Use schema_query with action='get' and name='onchain_operations' to retrieve the complete parameter schema. For individual operation schemas (e.g., 'onchain_operations_permission'), use schema_query with action='list_operations' to see all available operation schemas.",
             inputSchema: OnchainOperationsSchema,
             outputSchema: CallOutputSchema,
             annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
@@ -139,18 +139,22 @@ export const TOOL_REGISTRY = [
         handler: handleWatchQueryOperations,
         config: {
             title: "🔍 Data Query Toolkit",
-            description: "WOWOK data query toolkit — 9 query types covering local device data and on-chain blockchain data:\n\n"
+            description: "WOWOK data query toolkit — 13 query types covering local device data and on-chain blockchain data:\n\n"
                 + "LOCAL (device-only, never on-chain):\n"
                 + "1. local_mark_list — Query your LOCAL address book: maps human-readable names to blockchain addresses with optional tags. Use to resolve names→addresses or find addresses by tag.\n"
                 + "2. account_list — Query your LOCAL accounts (addresses, messenger status, suspension state). Use filter.includePubkey=true to also include public keys. Use to discover available accounts before operations.\n"
                 + "3. local_info_list — Query your LOCAL private info: sensitive data like delivery addresses, phone numbers, contacts stored ONLY on this device.\n"
                 + "4. token_list — Query cached token metadata: symbol, decimals, icon URL, description for tokens previously fetched from chain. Use to look up token precision/decimals before performing token operations. Returns: TokenTypeInfo[] (type, alias, name, symbol, decimals, iconUrl).\n"
-                + "5. account_balance — Query an account's coin balance OR Paginated coin objects. Use balance=true for total amount, or coin={cursor,limit} to list individual coin objects. Supports multi-token via token_type parameter.\n"
+                + "5. account_balance — Query an account's coin balance OR Paginated coin objects. Use balance=true for total amount, or coin={cursor,limit} to list individual coin objects. Supports multi-token via token_type parameter. Results include `_money_display` with unit-converted values + decimals reminder.\n"
                 + "6. local_names — Query local names by a list of addresses. For each address, returns the resolved account name (if exists) and local mark name (if exists). Returns: { account?, local_mark?, address }[].\n\n"
                 + "ONCHAIN (blockchain):\n"
                 + "7. onchain_personal_profile — Query any user's PUBLIC on-chain profile: social links, reputation (likes/dislikes), personal info records, voting history, referrer.\n"
-                + "8. onchain_objects — Batch query on-chain WOWOK objects by ID or name: supports Service, Machine, Order, Treasury, Reward, Arb, Personal, Contact, and more.\n"
-                + "9. onchain_received — Query objects (Payments, Tokens, NFTs) received by a specific object. Supports pagination and type filter.\n\n"
+                + "8. onchain_objects — Batch query on-chain WOWOK objects by ID or name: supports Service, Machine, Order, Treasury, Reward, Arb, Personal, Contact, and more. Monetary fields include `_money_display` annotations (token type from the object's immutable generic).\n"
+                + "9. onchain_received — Query objects (Payments, Tokens, NFTs) received by a specific object. Supports pagination and type filter. CoinWrapper mode returns token-aware `_money_display`.\n"
+                + "10. onchain_transaction — Verify what a specific transaction did on-chain (status, object changes, balance changes, gas, events). Balance changes include `_money_display` (unit-converted via each change's own coin_type; signed amounts supported).\n"
+                + "11. onchain_object_history — FORENSICS: all transactions that touched an object (auditing only — prefer assemble_context for AI context building).\n"
+                + "12. onchain_address_activity — FORENSICS: all transactions sent by an address (auditing only).\n"
+                + "13. token_value_convert — Convert between raw on-chain smallest units (u64) and human unit values in EITHER direction (e.g. \"2200000000\" ↔ \"2.2\" WOW). Unit→raw is REFUSED when token precision cannot be resolved (never guesses decimals).\n\n"
                 + "For dynamic table data queries (pagination, table items), use the 'onchain_table_data' tool.\n\n"
                 + "💡 Schema hint: Use schema_query with action='get' and name='query_toolkit' to retrieve the exact parameter schema with all query types and field definitions.",
             inputSchema: WatchQueryOperationsSchema,
@@ -189,7 +193,7 @@ export const TOOL_REGISTRY = [
         handler: handleOnchainEvents,
         config: {
             title: "📅 Watch WoWok On-chain Events",
-            description: "Watch on-chain WoWok events by type. Supports arbitration events, new order events, progress events, demand presentation events, demand feedback events, and new entity registration events. Use pagination cursor for fetching large result sets.\n\n💡 Schema hint: Use schema_query with action='get' and name='onchain_events' to retrieve the exact parameter schema with all event types and field definitions.",
+            description: "Watch on-chain WoWok events by type. Supports arbitration events, new order events, progress events, demand presentation events, demand feedback events, and new entity registration events. Use pagination cursor for fetching large result sets. NewOrderEvent.amount includes `_money_display` annotation (unit-converted via the order's Service generic token type; raw-only with retry hint when precision is unavailable).\n\n💡 Schema hint: Use schema_query with action='get' and name='onchain_events' to retrieve the exact parameter schema with all event types and field definitions.",
             inputSchema: OnchainEventsInputSchema,
             outputSchema: OnchainEventsResultSchema,
             annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
@@ -201,7 +205,7 @@ export const TOOL_REGISTRY = [
         handler: handleWowokInfo,
         config: {
             title: "ℹ️ WoWok Build-in Information",
-            description: "Query WoWok protocol information: 'constants', 'built-in permissions', 'guard instructions', 'current network', 'value types', or 'mainnet bridge tokens'. For 'mainnet bridge tokens': returns cross-chain bridge tokens (ETH, WETH, WBTC, USDC, USDT) with each token's symbol, WOW-side type tag (wowTypeTag), EVM address, decimals, and description. The wowTypeTag (format {address}::{module}::{struct}) can be used directly as the `type_parameter` of Service / Treasury / Reward / Allocation objects to set their payment token — e.g. use USDT's wowTypeTag to create a Service that accepts USDT payments.",
+            description: "Query WoWok protocol information: 'constants', 'built-in permissions', 'common mistakes', 'guard instructions', 'current network', 'value types', or 'mainnet bridge tokens'. Use 'common mistakes' to proactively learn known field-name/unit/workflow pitfalls before submitting an operation (e.g. filter operation:\"compensation_fund_add\"). For 'mainnet bridge tokens': returns cross-chain bridge tokens (ETH, WETH, WBTC, USDC, USDT) with each token's symbol, WOW-side type tag (wowTypeTag), EVM address, decimals, and description. The wowTypeTag (format {address}::{module}::{struct}) can be used directly as the `type_parameter` of Service / Treasury / Reward / Allocation objects to set their payment token — e.g. use USDT's wowTypeTag to create a Service that accepts USDT payments.",
             inputSchema: ProtocolInfoQuerySchema,
             outputSchema: ProtocolInfoResultSchema,
             annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
@@ -220,8 +224,14 @@ export const TOOL_REGISTRY = [
                 "  'list' - Show all available schemas (tools + on-chain operations). Start here to discover what exists.\n" +
                 "  'get' - Fetch the full input JSON Schema by name (e.g. 'onchain_operations'). Use with the 'name' param.\n" +
                 "  'get_output' - Fetch the output JSON Schema of a tool by name (e.g. 'onchain_operations'). Use with the 'name' param. Use this to understand a tool's return value structure.\n" +
+                "  'get_field' - Query a single field by dot-path (e.g. field_path='data.node.nodes.0.pairs'). Cheaper than 'get' when you only need one subtree.\n" +
                 "  'search' - Find schemas by keyword, matching name/title/description. Use with the 'query' param.\n" +
-                "  'list_operations' - Show only on-chain operation schemas (prefixed 'onchain_operations_'). Narrower than 'list'.",
+                "  'list_operations' - Show only on-chain operation schemas (prefixed 'onchain_operations_'). Narrower than 'list'.\n" +
+                "  'get_guard_templates' - Guard creation templates + best practices (e.g. signer_verification, progress_node_check). Omit 'template' to list all.\n" +
+                "  'search_examples' - Search verified example files by keyword (matches title/description/tags/operation_type/industry). Use with the 'query' param.\n" +
+                "  'get_tool_reference' - MCP tool usage reference (summaries, actions, prerequisites, notes). Pass name='<tool>' for one tool, query='<keyword>' to search, or omit for the full catalog.\n" +
+                "  'get_guard_design_patterns' - Curated Guard design patterns (business requirement → logic tree template). Pass name='<pattern_id>', query='<host>' (e.g. 'service_buy_guard', 'machine_forward'), or omit for the full catalog.\n" +
+                "  'get_safety_rules' - Safety rule tables sunk from the wowok-safety skill: object reuse, immutability-after-publish, LOCAL/ONCHAIN/QUERY classification, naming conventions.",
             inputSchema: SchemaQueryInputSchema,
             outputSchema: SchemaQueryOutputSchema,
             annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
@@ -286,6 +296,39 @@ export const TOOL_REGISTRY = [
                 "  • refresh_objects — Refresh object cache from chain (batch query, rate-limited).\n" +
                 "  • get_object_diff — Get field-level diff of an object between two timestamps.\n\n" +
                 "═══════════════════════════════════════════════════════════════\n" +
+                "  INDUSTRY MODE RECOMMENDATION + REGISTRY (9 actions, GLM6/92 §E)\n" +
+                "═══════════════════════════════════════════════════════════════\n" +
+                "  • recommend_industry — CALL THIS FIRST when the user describes a business without naming an industry. " +
+                "Returns top-3 similar industries + verified reference examples ('from scratch vs giants' shoulders').\n" +
+                "  • list_modes — List builtin industry modes + your custom modes.\n" +
+                "  • derive_user_mode — Derive a custom mode from a builtin (modify machine_shape/allocator/config). R-M1-11 enforced.\n" +
+                "  • evolve_user_mode — Iterate a custom mode (version bump + evolution history).\n" +
+                "  • register_user_mode — Register a fully custom mode (requires machine_shape + key_risk).\n" +
+                "  • unregister_user_mode — Delete a custom mode.\n" +
+                "  • register_custom_metric / register_custom_constraint — Extend the evaluation registries.\n" +
+                "  • list_metrics_constraints — List metrics + constraints (filterable by type/scope).\n\n" +
+                "═══════════════════════════════════════════════════════════════\n" +
+                "  INTENT → RISK → SUBSTEP PIPELINE (3 actions, GLM5-31 §V3/V4)\n" +
+                "═══════════════════════════════════════════════════════════════\n" +
+                "  • analyze_intent (C1) — Business intent text → parsed intent (primary/secondary objects, " +
+                "detected scenes, industry) + per-object puzzle snapshots + recommended creation order. " +
+                "Required: intent.\n" +
+                "  • aggregate_risks (C2) — Puzzle snapshots → calibrated risks (CRITICAL/HIGH/MEDIUM/LOW/INFO) " +
+                "with blocking status (RISK_BLOCKED / RISK_PENDING_CONFIRM / RISK_PASSED). Required: project + " +
+                "(puzzles OR intent — when intent is given, analyze_intent runs first automatically). " +
+                "Optional: planned_objects (OBJECT_REUSE check), planned_operations (IMMUTABILITY check).\n" +
+                "  • trace_substeps (C3) — Substep execution records → DAG coherence analysis (dangling inputs, " +
+                "circular refs, missing outputs, cross-step breaks, topological order, D-10 verdict). " +
+                "Required: project + substeps.\n\n" +
+                "═══════════════════════════════════════════════════════════════\n" +
+                "  MERCHANT ONBOARDING WIZARD (1 action, GLM6/93 §5)\n" +
+                "═══════════════════════════════════════════════════════════════\n" +
+                "  • merchant_guide — 10-step guided flow from 'I want to sell X' to a validated creation plan: " +
+                "intent analysis → industry matching → module adoption → semantic blueprint → evaluation preview → " +
+                "harness check → ordered creation plan. Stateless: pass guide_state UNCHANGED between calls, " +
+                "advance via guide_confirm. NEVER executes on-chain — materialize the plan via create_project + " +
+                "onchain_operations. Required: intent (first call) or guide_state.\n\n" +
+                "═══════════════════════════════════════════════════════════════\n" +
                 "  CONTEXT ASSEMBLY (1 action)\n" +
                 "═══════════════════════════════════════════════════════════════\n" +
                 "  • assemble_context — Query on-chain object states + extract embedded history + optional events, " +
@@ -462,10 +505,10 @@ const WOWOK_TOOL_DESCRIPTION = [
     "Projects are the core organizing unit for all WoWok workflows. The policy is context-aware:",
     "",
     "CASE 1 — COMPLEX REQUIREMENT (user wants to build/deploy a full service):",
-    "  Examples: '搭建旅行地陪服务', '开一个玩具店', '创建租赁服务'",
+    "  Examples: 'build a travel guide service', 'open a toy store', 'create a rental service'",
     "  → You MUST auto-create a project FIRST, then create objects.",
     "  → Check for similar existing projects first: project_operation action='list_projects'",
-    "    If similar projects exist (same industry), remind the user: '发现类似项目 X, 是否复用或新建?'",
+    "    If similar projects exist (same industry), remind the user: 'Found similar project X. Reuse or create new?'",
     "  → Workflow:",
     "    1. project_operation action='create_project' (perspective='producer', project_industry=<best match>)",
     "    2. Create on-chain objects via onchain_operations with env.project='<prefix>' (auto-tags + auto-associates to SQLite project)",
@@ -475,11 +518,11 @@ const WOWOK_TOOL_DESCRIPTION = [
     "    6. Report results, fix critical findings, then publish Service",
     "",
     "CASE 2 — SINGLE OBJECT CREATION (user wants one specific object):",
-    "  Examples: '创建一个Permission', '添加一个Contact', '建一个Guard'",
+    "  Examples: 'create a Permission', 'add a Contact', 'build a Guard'",
     "  → Do NOT auto-create a project. If the user has an existing project, create with env.project='<prefix>' to auto-associate.",
     "  → If no existing project, after creation, REMIND the user:",
-    "    '此对象已创建。建议将其加入一个项目以便管理: project_operation action=\"add_object\"",
-    "    如还没有项目, 可用 action=\"create_project\" 新建。现有项目: [list projects if any]'",
+    "    'This object has been created. Consider adding it to a project for management: project_operation action=\"add_object\"",
+    "    If no project exists yet, use action=\"create_project\" to create one. Existing projects: [list projects if any]'",
     "  → If the user then says 'yes, create a project' or 'add to project X', proceed accordingly.",
     "",
     "CASE 3 — CONSUMER FLOW (user wants to buy/evaluate a service):",
@@ -545,6 +588,150 @@ function formatZodErrors(error, input) {
         return `${path} [${code}]: ${message}${extras}`;
     });
 }
+function generateSuggestion(code, issue, receivedValue) {
+    const issueAny = issue;
+    switch (code) {
+        case "invalid_type": {
+            const expected = issueAny.expected;
+            const received = issueAny.received;
+            if (expected === "number" && typeof receivedValue === "string") {
+                return `Convert to number: ${Number(receivedValue)}`;
+            }
+            if (expected === "string") {
+                return `Wrap in quotes or call String(...)`;
+            }
+            if (expected === "array") {
+                return `Wrap in array: [${JSON.stringify(receivedValue)}]`;
+            }
+            if (expected === "object") {
+                return `Provide an object, not a primitive`;
+            }
+            return `Convert value to ${expected ?? "the expected type"}`;
+        }
+        case "invalid_enum_value": {
+            const options = issueAny.options;
+            const optionsStr = Array.isArray(options)
+                ? options.map((v) => JSON.stringify(v)).join(" | ")
+                : String(options);
+            return `Use one of: ${optionsStr}`;
+        }
+        case "invalid_literal": {
+            const expected = issueAny.expected;
+            return `Use the exact value: ${JSON.stringify(expected)}`;
+        }
+        case "too_small": {
+            const minimum = issueAny.minimum;
+            const type = issueAny.type;
+            if (type === "array") {
+                return `Add at least ${minimum} element(s) to the array`;
+            }
+            if (type === "string") {
+                return `String must be at least ${minimum} character(s) long`;
+            }
+            if (type === "number") {
+                return `Use a value >= ${minimum}`;
+            }
+            return `Value must be >= ${minimum}`;
+        }
+        case "too_big": {
+            const maximum = issueAny.maximum;
+            const type = issueAny.type;
+            if (type === "array") {
+                return `Reduce array to at most ${maximum} element(s)`;
+            }
+            if (type === "string") {
+                return `Shorten string to at most ${maximum} character(s)`;
+            }
+            if (type === "number") {
+                return `Use a value <= ${maximum}`;
+            }
+            return `Value must be <= ${maximum}`;
+        }
+        case "unrecognized_keys": {
+            const keys = issueAny.keys;
+            return `Remove unknown field(s): ${(keys ?? []).join(", ")}. Check the schema for valid field names.`;
+        }
+        case "invalid_union": {
+            return `Value does not match any of the union variants. Check the schema for valid shapes.`;
+        }
+        case "invalid_string": {
+            const validation = issueAny.validation;
+            if (validation === "url")
+                return `Provide a valid URL string`;
+            if (validation === "email")
+                return `Provide a valid email string`;
+            if (validation === "uuid")
+                return `Provide a valid UUID string`;
+            if (validation === "regex")
+                return `String does not match the required pattern`;
+            return `Provide a valid string matching the validation: ${validation ?? "unknown"}`;
+        }
+        case "invalid_date": {
+            return `Provide a valid Date object or ISO date string`;
+        }
+        case "not_finite": {
+            return `Use a finite number (not Infinity or NaN)`;
+        }
+        case "invalid_arguments": {
+            return `Arguments do not match the expected schema`;
+        }
+        case "invalid_return_type": {
+            return `Return type does not match the expected schema`;
+        }
+        case "custom": {
+            return `Custom validation failed — see the field's description in the schema`;
+        }
+        default: {
+            return `Fix the value at '${issue.path.join(".")}' based on the schema`;
+        }
+    }
+}
+function formatZodErrorsStructured(error, input) {
+    return error.issues.map(issue => {
+        const path = issue.path.length > 0
+            ? issue.path.map(p => typeof p === "number" ? `[${p}]` : p).join(".").replace(".[", "[")
+            : "(root)";
+        const code = issue.code;
+        const message = issue.message;
+        const issueAny = issue;
+        let expected;
+        if (code === "invalid_type") {
+            const exp = issueAny.expected;
+            const rec = issueAny.received;
+            if (typeof exp === "string" && typeof rec === "string") {
+                expected = exp;
+            }
+        }
+        else if (code === "invalid_literal") {
+            const exp = issueAny.expected;
+            if (exp !== undefined) {
+                expected = typeof exp === "string" ? exp : JSON.stringify(exp);
+            }
+        }
+        else if (code === "invalid_enum_value") {
+            const options = issueAny.options;
+            if (Array.isArray(options)) {
+                expected = options.map((v) => JSON.stringify(v)).join(" | ");
+            }
+        }
+        else if (code === "too_big" || code === "too_small") {
+            const threshold = issueAny.maximum ?? issueAny.minimum;
+            if (threshold !== undefined) {
+                expected = String(threshold);
+            }
+        }
+        const receivedVal = extractValueAtPath(input, issue.path);
+        const suggestion = generateSuggestion(code, issue, receivedVal);
+        return {
+            path,
+            code,
+            message,
+            expected,
+            received_value: receivedVal,
+            suggestion,
+        };
+    });
+}
 function extractValueAtPath(input, path) {
     if (input === undefined || input === null || path.length === 0) {
         return undefined;
@@ -837,18 +1024,36 @@ async function handleWowok(args) {
         if (unknownFields.length > 0) {
             allErrors.push(`Unknown field(s): ${unknownFields.join(", ")}`);
         }
+        const structuredErrors = [];
+        if (!validationResult.success) {
+            structuredErrors.push(...formatZodErrorsStructured(validationResult.error, normalizedData));
+        }
+        if (unknownFields.length > 0) {
+            for (const f of unknownFields) {
+                structuredErrors.push({
+                    path: f,
+                    code: "unrecognized_keys",
+                    message: `Unknown field '${f}' is not allowed`,
+                    suggestion: `Remove field '${f}' or check the schema for valid field names`,
+                });
+            }
+        }
         const fullSchema = loadPreGeneratedSchema(normalizedToolName) ?? zodToJsonSchemaSafe(entry.config.inputSchema, normalizedToolName);
         const relevantSchema = extractRelevantSchema(fullSchema, normalizedToolName, normalizedData);
+        const firstSuggestion = structuredErrors[0]?.suggestion
+            ? ` FIRST ERROR SUGGESTION: ${structuredErrors[0].suggestion}`
+            : '';
         const errorPreview = allErrors.slice(0, 5).map((e, i) => `  ${i + 1}. ${e}`).join("\n");
         const schemaPreview = buildSchemaPreview(relevantSchema, normalizedToolName, normalizedData);
         const textContent = [
-            `Schema mismatch for ${normalizedToolName}. ${allErrors.length} error(s):`,
+            `Schema mismatch for ${normalizedToolName}. ${allErrors.length} error(s).${firstSuggestion}`,
             errorPreview,
             "",
             schemaPreview,
             "",
             "Fix the parameters based on the errors above and the schema summary, then retry.",
             `Full JSON Schema is in the structuredContent.schema.input field (cache it for future ${normalizedToolName} calls).`,
+            `Structured errors with fix suggestions are in structuredContent.result.structured_errors (ARCH-02).`,
         ].filter(Boolean).join("\n");
         return {
             content: [{
@@ -859,6 +1064,7 @@ async function handleWowok(args) {
                 result: {
                     status: "schema_mismatch",
                     errors: allErrors,
+                    structured_errors: structuredErrors,
                     hint: `Fix your parameters based on the schema below and retry. CACHE THIS SCHEMA for future ${normalizedToolName} calls — you don't need to query it again.`,
                 },
                 schema: {
@@ -903,12 +1109,19 @@ async function handleWowok(args) {
             const fullSchema = loadPreGeneratedSchema(normalizedToolName) ?? zodToJsonSchemaSafe(entry.config.inputSchema, normalizedToolName);
             const relevantSchema = extractRelevantSchema(fullSchema, normalizedToolName, normalizedData);
             const schemaPreview = buildSchemaPreview(relevantSchema, normalizedToolName, normalizedData);
+            const structuredErrors = [{
+                    path: "(runtime)",
+                    code: "schema_validation_error",
+                    message: errorMessage,
+                    suggestion: "Check the error message and the schema below for the correct field format",
+                }];
             const textContent = [
                 `Schema mismatch for ${normalizedToolName}: ${errorMessage}`,
                 "",
                 schemaPreview,
                 "",
                 "Fix the parameters and retry. Full JSON Schema is in structuredContent.schema.input.",
+                "Structured errors with fix suggestions are in structuredContent.result.structured_errors (ARCH-02).",
             ].join("\n");
             return {
                 content: [{
@@ -919,6 +1132,7 @@ async function handleWowok(args) {
                     result: {
                         status: "schema_mismatch",
                         errors: [errorMessage],
+                        structured_errors: structuredErrors,
                         hint: `Fix your parameters based on the schema below and retry. CACHE THIS SCHEMA for future ${normalizedToolName} calls.`,
                     },
                     schema: {
@@ -1055,7 +1269,7 @@ export function listTools() {
             name: "wowok",
             title: "WoWok MCP",
             description: WOWOK_TOOL_DESCRIPTION,
-            inputSchema: zodToJsonSchemaSafe(WowokToolDisplaySchema, "wowok"),
+            inputSchema: resolveSchemaRefs(zodToJsonSchemaSafe(WowokToolDisplaySchema, "wowok")),
         }];
 }
 export function registerAllTools(server) {