@wowok/agent-mcp 2.6.1 → 2.6.3

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

@@ -48149,16 +48149,19 @@ export declare const PermissionInfoTypeSchema: z.ZodObject<{
     name: z.ZodString;
     description: z.ZodString;
     object_type: z.ZodString;
+    operation: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     name: string;
     object_type: string;
     description: string;
     index: number;
+    operation?: string | undefined;
 }, {
     name: string;
     object_type: string;
     description: string;
     index: number;
+    operation?: string | undefined;
 }>;
 export declare const GuardInstructSchema: z.ZodObject<{
     name: z.ZodString;
@@ -48231,17 +48234,58 @@ export declare const PermissionFilterSchema: z.ZodObject<{
     name: z.ZodOptional<z.ZodString>;
     index: z.ZodOptional<z.ZodEffects<z.ZodNumber, number, number>>;
     description: z.ZodOptional<z.ZodString>;
+    operation: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     name?: string | undefined;
     description?: string | undefined;
     objectType?: import("@wowok/wowok").ObjectType | undefined;
+    operation?: string | undefined;
     index?: number | undefined;
 }, {
     name?: string | undefined;
     description?: string | undefined;
     objectType?: import("@wowok/wowok").ObjectType | undefined;
+    operation?: string | undefined;
     index?: number | undefined;
 }>;
+export declare const CommonMistakeInfoSchema: z.ZodObject<{
+    object_type: z.ZodString;
+    operation: z.ZodString;
+    category: z.ZodEnum<["field_name", "unit", "value_range", "workflow", "timing"]>;
+    mistake: z.ZodString;
+    correct_usage: z.ZodString;
+    wrong_example: z.ZodString;
+    correct_example: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    object_type: string;
+    category: "workflow" | "unit" | "field_name" | "value_range" | "timing";
+    operation: string;
+    mistake: string;
+    correct_usage: string;
+    wrong_example: string;
+    correct_example: string;
+}, {
+    object_type: string;
+    category: "workflow" | "unit" | "field_name" | "value_range" | "timing";
+    operation: string;
+    mistake: string;
+    correct_usage: string;
+    wrong_example: string;
+    correct_example: string;
+}>;
+export declare const CommonMistakeFilterSchema: z.ZodObject<{
+    object_type: z.ZodOptional<z.ZodString>;
+    operation: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodEnum<["field_name", "unit", "value_range", "workflow", "timing"]>>;
+}, "strip", z.ZodTypeAny, {
+    object_type?: string | undefined;
+    category?: "workflow" | "unit" | "field_name" | "value_range" | "timing" | undefined;
+    operation?: string | undefined;
+}, {
+    object_type?: string | undefined;
+    category?: "workflow" | "unit" | "field_name" | "value_range" | "timing" | undefined;
+    operation?: string | undefined;
+}>;
 export declare const BridgeTokenInfoSchema: z.ZodObject<{
     tokenId: z.ZodNumber;
     symbol: z.ZodString;
@@ -48283,15 +48327,18 @@ export declare const ProtocolInfoQuerySchema: z.ZodDiscriminatedUnion<"info", [z
         name: z.ZodOptional<z.ZodString>;
         index: z.ZodOptional<z.ZodEffects<z.ZodNumber, number, number>>;
         description: z.ZodOptional<z.ZodString>;
+        operation: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         name?: string | undefined;
         description?: string | undefined;
         objectType?: import("@wowok/wowok").ObjectType | undefined;
+        operation?: string | undefined;
         index?: number | undefined;
     }, {
         name?: string | undefined;
         description?: string | undefined;
         objectType?: import("@wowok/wowok").ObjectType | undefined;
+        operation?: string | undefined;
         index?: number | undefined;
     }>>;
 }, "strict", z.ZodTypeAny, {
@@ -48300,6 +48347,7 @@ export declare const ProtocolInfoQuerySchema: z.ZodDiscriminatedUnion<"info", [z
         name?: string | undefined;
         description?: string | undefined;
         objectType?: import("@wowok/wowok").ObjectType | undefined;
+        operation?: string | undefined;
         index?: number | undefined;
     } | undefined;
 }, {
@@ -48308,8 +48356,38 @@ export declare const ProtocolInfoQuerySchema: z.ZodDiscriminatedUnion<"info", [z
         name?: string | undefined;
         description?: string | undefined;
         objectType?: import("@wowok/wowok").ObjectType | undefined;
+        operation?: string | undefined;
         index?: number | undefined;
     } | undefined;
+}>, z.ZodObject<{
+    info: z.ZodLiteral<"common mistakes">;
+    filter: z.ZodOptional<z.ZodObject<{
+        object_type: z.ZodOptional<z.ZodString>;
+        operation: z.ZodOptional<z.ZodString>;
+        category: z.ZodOptional<z.ZodEnum<["field_name", "unit", "value_range", "workflow", "timing"]>>;
+    }, "strip", z.ZodTypeAny, {
+        object_type?: string | undefined;
+        category?: "workflow" | "unit" | "field_name" | "value_range" | "timing" | undefined;
+        operation?: string | undefined;
+    }, {
+        object_type?: string | undefined;
+        category?: "workflow" | "unit" | "field_name" | "value_range" | "timing" | undefined;
+        operation?: string | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    info: "common mistakes";
+    filter?: {
+        object_type?: string | undefined;
+        category?: "workflow" | "unit" | "field_name" | "value_range" | "timing" | undefined;
+        operation?: string | undefined;
+    } | undefined;
+}, {
+    info: "common mistakes";
+    filter?: {
+        object_type?: string | undefined;
+        category?: "workflow" | "unit" | "field_name" | "value_range" | "timing" | undefined;
+        operation?: string | undefined;
+    } | undefined;
 }>, z.ZodObject<{
     info: z.ZodLiteral<"guard instructions">;
     filter: z.ZodOptional<z.ZodObject<{
@@ -48379,16 +48457,19 @@ export declare const BuiltinPermissionSchema: z.ZodObject<{
         name: z.ZodString;
         description: z.ZodString;
         object_type: z.ZodString;
+        operation: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         name: string;
         object_type: string;
         description: string;
         index: number;
+        operation?: string | undefined;
     }, {
         name: string;
         object_type: string;
         description: string;
         index: number;
+        operation?: string | undefined;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     result: {
@@ -48396,6 +48477,7 @@ export declare const BuiltinPermissionSchema: z.ZodObject<{
         object_type: string;
         description: string;
         index: number;
+        operation?: string | undefined;
     }[];
 }, {
     result: {
@@ -48403,6 +48485,7 @@ export declare const BuiltinPermissionSchema: z.ZodObject<{
         object_type: string;
         description: string;
         index: number;
+        operation?: string | undefined;
     }[];
 }>;
 export declare const ProtocolInfoResultWrappedSchema: z.ZodDiscriminatedUnion<"info", [z.ZodObject<{
@@ -48441,16 +48524,19 @@ export declare const ProtocolInfoResultWrappedSchema: z.ZodDiscriminatedUnion<"i
         name: z.ZodString;
         description: z.ZodString;
         object_type: z.ZodString;
+        operation: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         name: string;
         object_type: string;
         description: string;
         index: number;
+        operation?: string | undefined;
     }, {
         name: string;
         object_type: string;
         description: string;
         index: number;
+        operation?: string | undefined;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     result: {
@@ -48458,6 +48544,7 @@ export declare const ProtocolInfoResultWrappedSchema: z.ZodDiscriminatedUnion<"i
         object_type: string;
         description: string;
         index: number;
+        operation?: string | undefined;
     }[];
     info: "built-in permissions";
 }, {
@@ -48466,8 +48553,58 @@ export declare const ProtocolInfoResultWrappedSchema: z.ZodDiscriminatedUnion<"i
         object_type: string;
         description: string;
         index: number;
+        operation?: string | undefined;
     }[];
     info: "built-in permissions";
+}>, z.ZodObject<{
+    info: z.ZodLiteral<"common mistakes">;
+    result: z.ZodArray<z.ZodObject<{
+        object_type: z.ZodString;
+        operation: z.ZodString;
+        category: z.ZodEnum<["field_name", "unit", "value_range", "workflow", "timing"]>;
+        mistake: z.ZodString;
+        correct_usage: z.ZodString;
+        wrong_example: z.ZodString;
+        correct_example: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        object_type: string;
+        category: "workflow" | "unit" | "field_name" | "value_range" | "timing";
+        operation: string;
+        mistake: string;
+        correct_usage: string;
+        wrong_example: string;
+        correct_example: string;
+    }, {
+        object_type: string;
+        category: "workflow" | "unit" | "field_name" | "value_range" | "timing";
+        operation: string;
+        mistake: string;
+        correct_usage: string;
+        wrong_example: string;
+        correct_example: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    result: {
+        object_type: string;
+        category: "workflow" | "unit" | "field_name" | "value_range" | "timing";
+        operation: string;
+        mistake: string;
+        correct_usage: string;
+        wrong_example: string;
+        correct_example: string;
+    }[];
+    info: "common mistakes";
+}, {
+    result: {
+        object_type: string;
+        category: "workflow" | "unit" | "field_name" | "value_range" | "timing";
+        operation: string;
+        mistake: string;
+        correct_usage: string;
+        wrong_example: string;
+        correct_example: string;
+    }[];
+    info: "common mistakes";
 }>, z.ZodObject<{
     info: z.ZodLiteral<"guard instructions">;
     result: z.ZodArray<z.ZodObject<{
@@ -48652,16 +48789,19 @@ export declare const ProtocolInfoResultSchema: z.ZodObject<{
             name: z.ZodString;
             description: z.ZodString;
             object_type: z.ZodString;
+            operation: z.ZodOptional<z.ZodString>;
         }, "strip", z.ZodTypeAny, {
             name: string;
             object_type: string;
             description: string;
             index: number;
+            operation?: string | undefined;
         }, {
             name: string;
             object_type: string;
             description: string;
             index: number;
+            operation?: string | undefined;
         }>, "many">;
     }, "strip", z.ZodTypeAny, {
         result: {
@@ -48669,6 +48809,7 @@ export declare const ProtocolInfoResultSchema: z.ZodObject<{
             object_type: string;
             description: string;
             index: number;
+            operation?: string | undefined;
         }[];
         info: "built-in permissions";
     }, {
@@ -48677,8 +48818,58 @@ export declare const ProtocolInfoResultSchema: z.ZodObject<{
             object_type: string;
             description: string;
             index: number;
+            operation?: string | undefined;
         }[];
         info: "built-in permissions";
+    }>, z.ZodObject<{
+        info: z.ZodLiteral<"common mistakes">;
+        result: z.ZodArray<z.ZodObject<{
+            object_type: z.ZodString;
+            operation: z.ZodString;
+            category: z.ZodEnum<["field_name", "unit", "value_range", "workflow", "timing"]>;
+            mistake: z.ZodString;
+            correct_usage: z.ZodString;
+            wrong_example: z.ZodString;
+            correct_example: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            object_type: string;
+            category: "workflow" | "unit" | "field_name" | "value_range" | "timing";
+            operation: string;
+            mistake: string;
+            correct_usage: string;
+            wrong_example: string;
+            correct_example: string;
+        }, {
+            object_type: string;
+            category: "workflow" | "unit" | "field_name" | "value_range" | "timing";
+            operation: string;
+            mistake: string;
+            correct_usage: string;
+            wrong_example: string;
+            correct_example: string;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        result: {
+            object_type: string;
+            category: "workflow" | "unit" | "field_name" | "value_range" | "timing";
+            operation: string;
+            mistake: string;
+            correct_usage: string;
+            wrong_example: string;
+            correct_example: string;
+        }[];
+        info: "common mistakes";
+    }, {
+        result: {
+            object_type: string;
+            category: "workflow" | "unit" | "field_name" | "value_range" | "timing";
+            operation: string;
+            mistake: string;
+            correct_usage: string;
+            wrong_example: string;
+            correct_example: string;
+        }[];
+        info: "common mistakes";
     }>, z.ZodObject<{
         info: z.ZodLiteral<"guard instructions">;
         result: z.ZodArray<z.ZodObject<{
@@ -48840,8 +49031,20 @@ export declare const ProtocolInfoResultSchema: z.ZodObject<{
             object_type: string;
             description: string;
             index: number;
+            operation?: string | undefined;
         }[];
         info: "built-in permissions";
+    } | {
+        result: {
+            object_type: string;
+            category: "workflow" | "unit" | "field_name" | "value_range" | "timing";
+            operation: string;
+            mistake: string;
+            correct_usage: string;
+            wrong_example: string;
+            correct_example: string;
+        }[];
+        info: "common mistakes";
     } | {
         result: {
             name: string;
@@ -48891,8 +49094,20 @@ export declare const ProtocolInfoResultSchema: z.ZodObject<{
             object_type: string;
             description: string;
             index: number;
+            operation?: string | undefined;
         }[];
         info: "built-in permissions";
+    } | {
+        result: {
+            object_type: string;
+            category: "workflow" | "unit" | "field_name" | "value_range" | "timing";
+            operation: string;
+            mistake: string;
+            correct_usage: string;
+            wrong_example: string;
+            correct_example: string;
+        }[];
+        info: "common mistakes";
     } | {
         result: {
             name: string;
@@ -75389,6 +75604,8 @@ export type ServiceSale = z.infer<typeof ServiceSaleSchema>;
 export type PurchasedItem = z.infer<typeof PurchasedItemSchema>;
 export type ConstantItem = z.infer<typeof ConstantItemSchema>;
 export type PermissionInfoType = z.infer<typeof PermissionInfoTypeSchema>;
+export type CommonMistakeInfo = z.infer<typeof CommonMistakeInfoSchema>;
+export type CommonMistakeFilter = z.infer<typeof CommonMistakeFilterSchema>;
 export type BridgeTokenInfo = z.infer<typeof BridgeTokenInfoSchema>;
 export type ProtocolInfoQuery = z.infer<typeof ProtocolInfoQuerySchema>;
 export type ProtocolInfoResult = z.infer<typeof ProtocolInfoResultSchema>;

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"),
@@ -227,15 +228,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 +265,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 +528,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 +560,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),
@@ -977,8 +980,11 @@ 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 +1300,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 +1334,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 +1367,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 +1397,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'),