@wowok/agent-mcp 2.6.1 → 2.6.4

package/dist/schema/query/index.js

@@ -40,11 +40,12 @@ export const RecipientSchema = z.union([
     z.object({ GuardIdentifier: GuardIdentifierSchema }).describe("Guard verified recipient ID. Get recipient ID from specified data index in Guard table. The ID must be of address type."),
     z.object({ Entity: AccountOrMark_AddressSchema }).describe("Static address resolved via LocalMark. " +
         "Format: {Entity: {name_or_address: 'mark_name'}} — NOTE: Entity is an OBJECT with name_or_address field, NOT a bare string."),
-    z.object({ Signer: z.literal("signer") }).describe("Current transaction signer ID"),
+    z.object({ Signer: z.literal("signer") }).describe("Current transaction signer (tx_context::sender) at the time of the alloc() call. " +
+        "For refunds, the Order owner must call alloc_by_guard themselves to receive the funds."),
 ]).describe("Recipient ID. Three forms:\n" +
-    "  - {GuardIdentifier: u8}  — resolved from Passport at allocation time\n" +
-    "  - {Entity: {name_or_address: 'mark_name'}}  — static address via LocalMark (recommended)\n" +
-    "  - {Signer: 'signer'}  — transaction sender (e.g. self-refund)");
+    "  - {GuardIdentifier: u8}  — DYNAMIC address resolved from Passport at alloc() time\n" +
+    "  - {Entity: {name_or_address: 'mark_name'}}  — FIXED static address via LocalMark (recommended)\n" +
+    "  - {Signer: 'signer'}  — transaction sender at alloc() time (e.g. self-refund; customer must call alloc_by_guard themselves)");
 export const RecordsInEntitySchema = z.object({
     name: z.string().describe("Record name"),
     value_type: ValueTypeSchema.describe("Value type"),
@@ -120,8 +121,11 @@ export const ServiceSaleSchema = z.object({
     wip: z.string().describe("WIP file URL. EMPTY string \"\" skips verification (TESTING ONLY). " +
         "Production MUST use a real HTTP URL pointing to a .wip file generated by the wip_file tool. " +
         "Example: \"https://cdn.example.com/products/phone_v1.wip\""),
-    wip_hash: z.string().describe("WIP file hash (hex string). EMPTY string \"\" skips hash comparison (TESTING ONLY). " +
-        "Production: fill with the hash you saw when viewing the product, to prevent merchant replacing the WIP file before order."),
+    wip_hash: z.string().describe("SHA-256 hash (hex string) of the sale's WIP file, committed on-chain by the merchant. " +
+        "BUY RULE: if this is NON-EMPTY, the buyer MUST pass this exact value as wip_hash when creating an order " +
+        "(ServiceBuyItem.wip_hash) — NEVER use \"\". Pinning the on-chain hash prevents the merchant from replacing " +
+        "the WIP file (a legitimate update) between the buyer's view and order placement, ensuring 'what you see is " +
+        "what you get'. EMPTY means no hash was committed (TESTING ONLY, no delivery-integrity guarantee)."),
 }).describe("Service sale");
 export const PurchasedItemSchema = z.object({
     name: LongNameSchema.describe("Name of the product or service"),
@@ -227,15 +231,20 @@ export const AllocationModeSchema = z.union([
     "Use Surplus to capture remainder (e.g., platform fee + host gets rest). " +
     "Accepts string ('Amount'/'Rate'/'Surplus', recommended) or number (0/1/2).");
 export const AllocationSharingSchema = z.object({
-    who: RecipientSchema.describe("Recipient of this allocation. Three forms:\n" +
-        "• { GuardIdentifier: u8 } — resolved from Passport at allocation time. " +
+    who: RecipientSchema.describe("Recipient of this allocation. Three forms — each resolves the address at a DIFFERENT time:\n" +
+        "• { GuardIdentifier: u8 } — DYNAMIC address resolved from Passport at alloc() time (contract calls passport::submission_get). " +
         "Use 0 for Order owner in Service-integrated mode (Customer who created the Order). " +
         "The identifier must match a Guard table entry with b_submission=true. " +
-        "If Passport has no matching submission, contract aborts with E_VERIFY_FAILED.\n" +
-        "• { Entity: { name_or_address: '...' } } — static address resolved via LocalMark. " +
-        "Use for known recipients (e.g., 'turo_host', or a Treasury object address).\n" +
-        "• 'Signer' — the transaction sender (tx_context::sender). " +
-        "Use when the recipient is the current signer (e.g., self-refund scenarios)."),
+        "If Passport has no matching submission, contract aborts with E_VERIFY_FAILED. " +
+        "Use when the recipient address is not known at config time and must be supplied via Guard submission data.\n" +
+        "• { Entity: { name_or_address: '...' } } — FIXED address resolved via LocalMark at SDK build time (passed to contract as a literal address). " +
+        "Use for known recipients (e.g., 'turo_host', or a Treasury object address). " +
+        "Use when the recipient is a stable, known address (e.g., operator receives rent, platform fee to treasury).\n" +
+        "• 'Signer' — the transaction sender at the time of the alloc() call (tx_context::sender). " +
+        "RESOLVED AT EXECUTION TIME, not at config time. " +
+        "For refunds: the customer (Order owner) must call alloc_by_guard THEMSELVES so that tx_context::sender resolves to THEIR address — " +
+        "if the operator calls alloc_by_guard, the operator becomes the recipient (Signer = operator), NOT the customer. " +
+        "Use when the recipient is whoever submits the allocation transaction (e.g., customer receives refund)."),
     sharing: BalanceTypeSchema.describe("Allocation value. SEMANTICS DEPEND ON `mode`:\n" +
         "• mode='Amount': absolute amount in smallest unit (e.g., '750000000' for 0.75 WOW, '250000000' for 0.25 WOW). " +
         "Allocated first; sum of Amount items cached as `fix`.\n" +
@@ -259,11 +268,14 @@ export const AllocatorSchema = z.object({
     fix: BalanceTypeSchema.optional().describe("OUTPUT-ONLY (query result). Cached sum of all Amount-mode `sharing` values in this Allocator. " +
         "Computed by the contract during `allocator_add` — DO NOT set this field at creation. " +
         "Used internally to compute `total_rates = balance - fix` for Rate allocation."),
-    max: z.union([BalanceTypeSchema, z.null()]).optional().describe("Maximum allocation cap (optional). Has THREE effects:\n" +
+    max: z.union([BalanceTypeSchema, z.null()]).optional().describe("Maximum allocation cap (OPTIONAL — omit the field or set to null to disable the cap; do NOT set to 0 as that means a cap of zero). " +
+        "Passed through to the contract as Option<u64> via allocator_add(): when null/omitted the contract treats it as `none` (no cap); " +
+        "when set, the contract enforces it. Has THREE effects when set:\n" +
         "1. Construction: sum of Amount items must be <= max (EAMOUNT_EXCEEDS_MAX=13)\n" +
         "2. Rate execution: total_rates = max - fix (instead of balance - fix)\n" +
         "3. Surplus execution: surplus_amount = max - alloced_amount (instead of balance - alloced_amount)\n" +
-        "Use when you want to cap total allocation regardless of Order balance (e.g., cap payout to declared amount)."),
+        "Use when you want to cap total allocation regardless of Order balance (e.g., cap payout to declared amount). " +
+        "SDK pre-validates Amount sum <= max at build time to give actionable error messages before on-chain abort."),
 }).describe("Fund allocator — a complete allocation strategy triggered by a Guard. " +
     "Contains a sharing[] array where items can mix Amount/Rate/Surplus modes. " +
     "When the Guard passes, the contract allocates funds in strict order: Amount → Rate → Surplus.");
@@ -519,7 +531,7 @@ export const GuardNodeSchema = z.lazy(() => z.discriminatedUnion('type', [
             identifier: GuardIdentifierSchema,
             convert_witness: WitnessTypeSchema.optional(),
         }).strict().describe("The object to query from the Guard table."),
-        parameters: z.array(GuardNodeSchema).describe("Parameters required by the query (must match the query's expected parameters type)."),
+        parameters: z.array(GuardNodeSchema).optional().describe("Parameters required by the query. Optional — defaults to empty array []. Many queries (e.g. progress.current, order.service) take no parameters; for those, this field can be omitted."),
     }).strict().describe(`Returns the result of executing a data query instruction on the specified object. The return type depends on the query being executed. SPECIAL NOTE for EntityLinker/EntityRegistrar queries: Use system addresses in the Guard table -${ENTITY_LINKER_ADDRESS} for EntityLinker queries, ${ENTITY_REGISTRAR_ADDRESS} for EntityRegistrar queries.`),
     z.object({
         type: z.literal('logic_as_u256_greater_or_equal'),
@@ -551,18 +563,12 @@ export const GuardNodeSchema = z.lazy(() => z.discriminatedUnion('type', [
     }).strict().describe("Returns Bool. Computed by inverting the boolean value of the child node (true -> false, false -> true)."),
     z.object({
         type: z.literal('logic_and'),
-        nodes: z.array(GuardNodeSchema),
-    }).strict().describe(`Returns Bool. Requires 2-${MAX_MULTI_OPERANDS} boolean nodes. Computed by performing logical AND on all child node values. Returns true if ALL are true, otherwise false.`)
-        .refine((v) => v.nodes.length >= 2 && v.nodes.length <= MAX_MULTI_OPERANDS, {
-        message: `logic_and requires 2-${MAX_MULTI_OPERANDS} child nodes. For a single condition, use the comparison node directly as root (e.g. logic_equal), do NOT wrap with logic_and.`,
-    }),
+        nodes: z.array(GuardNodeSchema).min(2, `logic_and requires at least 2 child nodes. For a single condition, use the comparison node directly as root (e.g. logic_equal), do NOT wrap with logic_and.`).max(MAX_MULTI_OPERANDS, `logic_and allows at most ${MAX_MULTI_OPERANDS} child nodes.`),
+    }).strict().describe(`Returns Bool. Requires 2-${MAX_MULTI_OPERANDS} boolean nodes. Computed by performing logical AND on all child node values. Returns true if ALL are true, otherwise false.`),
     z.object({
         type: z.literal('logic_or'),
-        nodes: z.array(GuardNodeSchema),
-    }).strict().describe(`Returns Bool. Requires 2-${MAX_MULTI_OPERANDS} boolean nodes. Computed by performing logical OR on all child node values. Returns true if ANY is true, otherwise false.`)
-        .refine((v) => v.nodes.length >= 2 && v.nodes.length <= MAX_MULTI_OPERANDS, {
-        message: `logic_or requires 2-${MAX_MULTI_OPERANDS} child nodes. For a single condition, use the comparison node directly as root (e.g. logic_equal), do NOT wrap with logic_or.`,
-    }),
+        nodes: z.array(GuardNodeSchema).min(2, `logic_or requires at least 2 child nodes. For a single condition, use the comparison node directly as root (e.g. logic_equal), do NOT wrap with logic_or.`).max(MAX_MULTI_OPERANDS, `logic_or allows at most ${MAX_MULTI_OPERANDS} child nodes.`),
+    }).strict().describe(`Returns Bool. Requires 2-${MAX_MULTI_OPERANDS} boolean nodes. Computed by performing logical OR on all child node values. Returns true if ANY is true, otherwise false.`),
     z.object({
         type: z.literal('logic_string_contains'),
         nodes: z.array(GuardNodeSchema),
@@ -972,13 +978,21 @@ export const MachineForwardSchema = z.object({
         "that progress is not modified by this forward. " +
         "For target-node verification after transition, bind the Guard to the Allocator instead " +
         "(allocation.alloc runs AFTER the state transition completes)."),
-}).strict().describe("Forward in Machine object");
+}).strict().refine((f) => (f.namedOperator !== null && f.namedOperator !== undefined) ||
+    (f.permissionIndex !== null && f.permissionIndex !== undefined), {
+    message: "One of 'namedOperator' or 'permissionIndex' must be provided for each forward. " +
+        "Use namedOperator:'' (empty string) when the ORDER OWNER operates this forward; " +
+        "use a permissionIndex (e.g. 1000) when the same operator acts for all orders.",
+}).describe("Forward in Machine object");
 export const MachineNodePairSchema = z.object({
     prev_node: z.string().describe("Previous node name. Empty string '' means initial entry node (the first node in the workflow)."),
     threshold: tolerantNumber.default(0).describe("Threshold to trigger node advancement. If total Forward weight is greater than or equal to threshold, node advancement is triggered."),
     forwards: z.array(MachineForwardSchema).describe("Forward list — operations to ENTER THIS NODE from prev_node. " +
+        "SEMANTIC CLARIFICATION: forwards describe INCOMING transitions (how to ARRIVE at this node), " +
+        "NOT outgoing transitions. Think of each forward as an 'entry door' to this node. " +
         "Example: pair {prev_node:'A', forwards:[{name:'Go'}]} means 'use Go to advance FROM A TO THIS NODE'. " +
         "For initial node (prev_node=''), forwards are operations to enter this node from the start state. " +
+        "DIAGRAM: A --[Go]--> B means the pair belongs to node B (destination), with prev_node='A'. " +
         "WARNING: forwards belong to the DESTINATION node's pair, NOT the source node. " +
         "Placing a forward on the wrong pair will cause Progress to get stuck."),
 }).strict().describe("Node pair in Machine object")
@@ -1294,11 +1308,12 @@ export const ConstantItemSchema = z.object({
     description: z.string().describe('Description')
 }).describe('Constant item');
 export const PermissionInfoTypeSchema = z.object({
-    index: z.number().describe('Permission index'),
-    name: z.string().describe('Name'),
-    description: z.string().describe('Description'),
-    object_type: z.string().describe('Object type')
-}).describe('Permission info type');
+    index: z.number().describe('Permission index (e.g. 315 for service.compensation_fund_deposit)'),
+    name: z.string().describe('Permission name (e.g. "service.compensation_fund_deposit")'),
+    description: z.string().describe('Description of what this permission allows'),
+    object_type: z.string().describe('Object type this permission belongs to (e.g. "Service", "Arbitration")'),
+    operation: z.optional(z.string()).describe('The SDK/MCP operation field name that triggers this permission check (e.g. "compensation_fund_add", "publish", "pause"). Undefined for permissions with no direct Call*_Data field (e.g. "*.new" permissions). Use this to answer: "What permission does operation X require?" by filtering with {operation: "compensation_fund_add"}.')
+}).describe('Permission info type — includes the operation field name that maps to this permission, so AI can look up required permissions by operation name.');
 export const GuardInstructSchema = z.object({
     name: z.string().describe('Name of the guard instruction'),
     id: z.number().int().describe('ID of the guard instruction (OperatorType or ContextType)'),
@@ -1327,8 +1342,23 @@ export const PermissionFilterSchema = z.object({
     objectType: z.optional(ObjectTypeSchema).describe('Object type filter'),
     name: z.optional(z.string()).describe('Name filter'),
     index: z.optional(PermissionIndexTypeSchema).describe('Index filter'),
-    description: z.optional(z.string()).describe('Description filter')
+    description: z.optional(z.string()).describe('Description filter'),
+    operation: z.optional(z.string()).describe('Filter by SDK/MCP operation field name (e.g. "compensation_fund_add"). Returns only permissions triggered by this operation. Use this to answer: "What permission does operation X require?"')
 }).describe('Permission filter');
+export const CommonMistakeInfoSchema = z.object({
+    object_type: z.string().describe('The object type this mistake applies to (e.g. "Service", "Arbitration")'),
+    operation: z.string().describe('The operation field name this mistake applies to (e.g. "compensation_fund_add", "voting_deadline")'),
+    category: z.enum(['field_name', 'unit', 'value_range', 'workflow', 'timing']).describe('Category of the mistake: field_name (wrong field name), unit (wrong unit like seconds vs ms), value_range (wrong expected value), workflow (wrong operation order), timing (wrong time constraint)'),
+    mistake: z.string().describe('Short description of the mistake'),
+    correct_usage: z.string().describe('The correct usage pattern'),
+    wrong_example: z.string().describe('Example of the wrong usage'),
+    correct_example: z.string().describe('Example of the correct usage')
+}).describe('A known common mistake for an on-chain operation. Use this to proactively warn users before they submit a transaction.');
+export const CommonMistakeFilterSchema = z.object({
+    object_type: z.optional(z.string()).describe('Filter by object type (e.g. "Service")'),
+    operation: z.optional(z.string()).describe('Filter by operation field name (e.g. "compensation_fund_add")'),
+    category: z.optional(z.enum(['field_name', 'unit', 'value_range', 'workflow', 'timing'])).describe('Filter by category (e.g. "field_name" for field-name mistakes, "unit" for unit mistakes)')
+}).describe('Filter for common mistakes. Use operation:"compensation_fund_add" to find mistakes for a specific operation.');
 export const BridgeTokenInfoSchema = z.object({
     tokenId: z.number().describe('On-chain token ID (mainnet: WBTC=1, ETH/WETH=2, USDC=3, USDT=4)'),
     symbol: z.string().describe('Token symbol/abbreviation (ETH, WETH, WBTC, USDC, USDT)'),
@@ -1345,8 +1375,12 @@ export const ProtocolInfoQuerySchema = z.discriminatedUnion('info', [
     }).strict().describe('Constants query'),
     z.object({
         info: z.literal('built-in permissions'),
-        filter: z.optional(PermissionFilterSchema).describe('Filter for built-in permissions')
-    }).strict().describe('Built-in permissions query'),
+        filter: z.optional(PermissionFilterSchema).describe('Filter for built-in permissions. Use operation:"compensation_fund_add" to find which permission a specific operation requires.')
+    }).strict().describe('Built-in permissions query. Each permission includes an optional "operation" field that maps to the SDK/MCP Call*_Data field name triggering it. Use this to answer: "What permission does operation X require?" — e.g. filter operation:"compensation_fund_add" returns permission index 315 (service.compensation_fund_deposit).'),
+    z.object({
+        info: z.literal('common mistakes'),
+        filter: z.optional(CommonMistakeFilterSchema).describe('Filter for common mistakes. Use operation:"compensation_fund_add" to find mistakes for a specific operation, or category:"field_name" for all field-name mistakes.')
+    }).strict().describe('Common mistakes query. Returns known field-name, unit, value-range, workflow, and timing pitfalls for on-chain operations. Use this to proactively warn users before submitting a transaction. Example: query operation:"compensation_fund_add" to learn about the {amount} vs {balance} field name mistake.'),
     z.object({
         info: z.literal('guard instructions'),
         filter: z.optional(GuardInstructFilterOptionsSchema).describe('Filter for guard instructions')
@@ -1371,7 +1405,11 @@ export const ProtocolInfoResultWrappedSchema = z.discriminatedUnion('info', [
     }),
     z.object({
         info: z.literal('built-in permissions'),
-        result: z.array(PermissionInfoTypeSchema).describe('Built-in permissions result')
+        result: z.array(PermissionInfoTypeSchema).describe('Built-in permissions result. Each item includes an optional "operation" field mapping to the SDK/MCP field name that triggers this permission.')
+    }),
+    z.object({
+        info: z.literal('common mistakes'),
+        result: z.array(CommonMistakeInfoSchema).describe('Common mistakes result. Each item documents a known pitfall (wrong field name, wrong unit, wrong workflow order, etc.) with wrong/correct examples.')
     }),
     z.object({
         info: z.literal('guard instructions'),
@@ -1534,6 +1572,20 @@ export const OnchainQueryResultSchema_Part3 = z.union([
         query_type: z.literal("onchain_address_activity"),
         result: z.union([TransactionHistoryAnswerSchema, z.undefined()]),
     }).strict(),
+    z.object({
+        query_type: z.literal("token_value_convert"),
+        result: z.object({
+            token_type: z.string().describe("Full token type used for conversion"),
+            symbol: z.string().optional().describe("Resolved token symbol"),
+            decimals: z.number().optional().describe("Resolved decimals N — the precision reminder"),
+            precision_known: z.boolean().describe("false → precision unavailable; conversion may have been impossible"),
+            direction: z.union([z.literal("raw_to_unit"), z.literal("unit_to_raw")]),
+            input: z.string().describe("Input value as provided"),
+            output: z.string().describe("Converted value (empty string when conversion was impossible)"),
+            error: z.string().optional().describe("Hard failure reason (e.g. unit→raw without known precision)"),
+            text: z.string().describe("One-line human text with the decimals reminder"),
+        }).strict().describe("Bidirectional token value conversion result — see Fund Processing Layer"),
+    }).strict(),
 ]);
 export const AllQueryResultsSchema = z.union([
     LocalQueryResultSchema,

package/dist/schema/schema-query/index.d.ts

@@ -1,21 +1,27 @@
 import { z } from "zod";
 export declare const SchemaQueryInputSchema: z.ZodObject<{
-    action: z.ZodEnum<["list", "get", "get_output", "search", "list_operations", "get_guard_templates", "get_field"]>;
+    action: z.ZodEnum<["list", "get", "get_output", "search", "list_operations", "get_guard_templates", "get_field", "search_examples", "get_tool_reference", "get_guard_design_patterns", "get_safety_rules", "get_templates"]>;
     name: z.ZodOptional<z.ZodString>;
     query: z.ZodOptional<z.ZodString>;
     field_path: z.ZodOptional<z.ZodString>;
     template: z.ZodOptional<z.ZodString>;
+    object_type: z.ZodOptional<z.ZodEnum<["guard", "machine", "service", "order", "progress", "arbitration", "treasury", "permission", "passport", "allocation", "reward"]>>;
+    params: z.ZodOptional<z.ZodString>;
     output_file: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
-    action: "get" | "search" | "list" | "get_output" | "list_operations" | "get_guard_templates" | "get_field";
+    action: "get" | "search" | "list" | "get_output" | "get_field" | "list_operations" | "get_guard_templates" | "search_examples" | "get_tool_reference" | "get_guard_design_patterns" | "get_safety_rules" | "get_templates";
+    params?: string | undefined;
     name?: string | undefined;
+    object_type?: "reward" | "permission" | "guard" | "allocation" | "service" | "machine" | "arbitration" | "treasury" | "order" | "progress" | "passport" | undefined;
     query?: string | undefined;
     field_path?: string | undefined;
     template?: string | undefined;
     output_file?: string | undefined;
 }, {
-    action: "get" | "search" | "list" | "get_output" | "list_operations" | "get_guard_templates" | "get_field";
+    action: "get" | "search" | "list" | "get_output" | "get_field" | "list_operations" | "get_guard_templates" | "search_examples" | "get_tool_reference" | "get_guard_design_patterns" | "get_safety_rules" | "get_templates";
+    params?: string | undefined;
     name?: string | undefined;
+    object_type?: "reward" | "permission" | "guard" | "allocation" | "service" | "machine" | "arbitration" | "treasury" | "order" | "progress" | "passport" | undefined;
     query?: string | undefined;
     field_path?: string | undefined;
     template?: string | undefined;
@@ -36,6 +42,36 @@ export declare const SchemaQueryOutputSchema: z.ZodObject<{
         name: string;
         description?: string | undefined;
         title?: string | undefined;
+    }>, "many">, z.ZodArray<z.ZodObject<{
+        file: z.ZodString;
+        title: z.ZodString;
+        description: z.ZodString;
+        tags: z.ZodArray<z.ZodString, "many">;
+        industry: z.ZodString;
+        operation_type: z.ZodString;
+        verified: z.ZodBoolean;
+        score: z.ZodNumber;
+        matched_fields: z.ZodArray<z.ZodString, "many">;
+    }, "strict", z.ZodTypeAny, {
+        description: string;
+        title: string;
+        score: number;
+        tags: string[];
+        file: string;
+        verified: boolean;
+        industry: string;
+        operation_type: string;
+        matched_fields: string[];
+    }, {
+        description: string;
+        title: string;
+        score: number;
+        tags: string[];
+        file: string;
+        verified: boolean;
+        industry: string;
+        operation_type: string;
+        matched_fields: string[];
     }>, "many">, z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodNull]>;
     message: z.ZodString;
     suggestions: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
@@ -46,6 +82,16 @@ export declare const SchemaQueryOutputSchema: z.ZodObject<{
         name: string;
         description?: string | undefined;
         title?: string | undefined;
+    }[] | {
+        description: string;
+        title: string;
+        score: number;
+        tags: string[];
+        file: string;
+        verified: boolean;
+        industry: string;
+        operation_type: string;
+        matched_fields: string[];
     }[] | null;
     success: boolean;
     action: string;
@@ -57,6 +103,16 @@ export declare const SchemaQueryOutputSchema: z.ZodObject<{
         name: string;
         description?: string | undefined;
         title?: string | undefined;
+    }[] | {
+        description: string;
+        title: string;
+        score: number;
+        tags: string[];
+        file: string;
+        verified: boolean;
+        industry: string;
+        operation_type: string;
+        matched_fields: string[];
     }[] | null;
     success: boolean;
     action: string;

package/dist/schema/schema-query/index.js

@@ -10,16 +10,21 @@ export const SchemaQueryInputSchema = z
         "list_operations",
         "get_guard_templates",
         "get_field",
+        "search_examples",
+        "get_tool_reference",
+        "get_guard_design_patterns",
+        "get_safety_rules",
+        "get_templates",
     ])
-        .describe("Action to perform: 'list' (all schemas), 'get' (specific input schema), 'get_output' (tool output schema), 'get_field' (field-path query e.g. field_path='data.node'), 'search' (by keyword), 'list_operations' (on-chain operations), 'get_guard_templates' (Guard creation templates + best practices)."),
+        .describe("Action to perform: 'list' (all schemas), 'get' (specific input schema), 'get_output' (tool output schema), 'get_field' (field-path query e.g. field_path='data.node'), 'search' (by keyword), 'list_operations' (on-chain operations), 'get_guard_templates' (Guard creation templates + best practices), 'search_examples' (search verified example files by keyword — matches title, description, tags, operation_type, industry), 'get_tool_reference' (MCP tool usage reference: summaries, actions, prerequisites, notes — sunk from wowok-tools skill), 'get_guard_design_patterns' (curated Guard design pattern catalog: business requirement → logic tree template — sunk from wowok-guard skill), 'get_safety_rules' (object reuse/immutability/operation-classification/naming rules — sunk from wowok-safety skill), 'get_templates' (unified template registry: ~90 parameterized templates across 11 object types — guard/machine/service/order/progress/arbitration/treasury/permission/passport/allocation/reward; omit 'template' to list metadata, provide 'template' for full detail, provide 'template' + 'params' to instantiate into executable JSON)."),
     name: z
         .string()
         .optional()
-        .describe("Schema/tool name for 'get'/'get_output'/'get_field' action (e.g., 'onchain_operations', 'onchain_operations_machine')."),
+        .describe("Schema/tool name for 'get'/'get_output'/'get_field'/'get_tool_reference' action (e.g., 'onchain_operations', 'onchain_operations_machine'), or pattern id for 'get_guard_design_patterns' (e.g., 'pattern.identity_check_allowlist')."),
     query: z
         .string()
         .optional()
-        .describe("Search query for 'search' action"),
+        .describe("Search query for 'search' action, keyword filter for 'get_tool_reference', or host filter for 'get_guard_design_patterns' (e.g. 'service_buy_guard', 'machine_forward', 'reward_claim')."),
     field_path: z
         .string()
         .optional()
@@ -27,7 +32,27 @@ export const SchemaQueryInputSchema = z
     template: z
         .string()
         .optional()
-        .describe("Guard template name for 'get_guard_templates' action. Omit to list all available templates. Available: signer_verification, progress_node_check, order_owner_verification, service_belonging_check, reward_not_claimed, combined_reward_guard."),
+        .describe("Guard template name for 'get_guard_templates' action. Omit to list all available templates. Available: signer_verification, progress_node_check, order_owner_verification, service_belonging_check, reward_not_claimed, combined_reward_guard. For 'get_templates': unified template id (e.g. 'tpl_buy_guard_whitelist', 'tpl_machine_ecommerce_standard', 'T-S-01', 'T-O-01', 'first_order')."),
+    object_type: z
+        .enum([
+        "guard",
+        "machine",
+        "service",
+        "order",
+        "progress",
+        "arbitration",
+        "treasury",
+        "permission",
+        "passport",
+        "allocation",
+        "reward",
+    ])
+        .optional()
+        .describe("Object-type filter for 'get_templates' list mode (e.g. 'guard' lists only Guard templates)."),
+    params: z
+        .string()
+        .optional()
+        .describe("JSON-encoded parameter object for 'get_templates' instantiation mode (e.g. '{\"whitelist\":[\"0xabc\"]}'). Required params are declared in each template's 'parameters' list (see detail mode)."),
     output_file: z
         .string()
         .optional()
@@ -41,6 +66,19 @@ const SchemaListItemSchema = z
     description: z.string().optional().describe("Short description, if known."),
 })
     .strict();
+const ExampleSearchResultSchema = z
+    .object({
+    file: z.string().describe("Example file name (e.g. 'rental-ziroom-service-create.json')."),
+    title: z.string().describe("Human-readable title from the example metadata."),
+    description: z.string().describe("Longer description from the example metadata."),
+    tags: z.array(z.string()).describe("Tags from the example metadata."),
+    industry: z.string().describe("Industry category (e.g. 'rental', 'retail', 'general')."),
+    operation_type: z.string().describe("Operation type (e.g. 'service', 'machine', 'guard', 'permission')."),
+    verified: z.boolean().describe("Whether the example is marked as verified."),
+    score: z.number().describe("Relevance score — number of fields that matched the query (0-5)."),
+    matched_fields: z.array(z.string()).describe("List of fields that matched the query."),
+})
+    .strict();
 export const SchemaQueryOutputSchema = z
     .object({
     success: z.boolean().describe("Whether the request was successful"),
@@ -48,10 +86,11 @@ export const SchemaQueryOutputSchema = z
     data: z
         .union([
         z.array(SchemaListItemSchema).describe("List of schema summaries (list/search/list_operations)."),
-        z.record(z.unknown()).describe("JSON Schema object (get/get_output/get_field) or Guard template data."),
+        z.array(ExampleSearchResultSchema).describe("List of matching examples (search_examples)."),
+        z.record(z.unknown()).describe("JSON Schema object (get/get_output/get_field), Guard template data, tool reference data (get_tool_reference), Guard design pattern catalog (get_guard_design_patterns), or safety rules tables (get_safety_rules)."),
         z.null().describe("No data — lookup failed or returned nothing, or data was written to output_file."),
     ])
-        .describe("Response data — array of schema summaries for list-like actions, JSON Schema object for get/get_output/get_field, Guard template data for get_guard_templates, null on failure or when output_file is used."),
+        .describe("Response data — array of schema summaries for list-like actions, array of example results for search_examples, JSON Schema object for get/get_output/get_field, Guard template data for get_guard_templates, null on failure or when output_file is used."),
     message: z.string().describe("Human-readable message describing the result"),
     suggestions: z
         .array(z.string())