@varun-ai07/covenant-mcp 1.2.2 → 1.3.0

package/dist/tools/escrow.js

@@ -11,7 +11,9 @@ import { z } from "zod";
 import { parseEther, formatEther, isAddress } from "viem";
 import { loadAbi, CONTRACTS, getAccount } from "../config.js";
 import { executeOrPrepare, readContract } from "../handlers/wallet.js";
-import { formatTxResult, formatReadResult, formatError } from "../handlers/transactions.js";
+import { formatTxResult, formatReadResult } from "../handlers/transactions.js";
+import { formatSuccess, formatStructuredError, parseContractError } from "../lib/formatResponse.js";
+import { ethAddress, ethAmount, ipfsCid, unixDeadline, taskId as taskIdSchema, priority as prioritySchema } from "../lib/schemaHelpers.js";
 import { TASK_STATUS } from "../types.js";
 const ABI = loadAbi("TaskEscrow");
 // Input validation schemas
@@ -53,54 +55,66 @@ export function registerEscrowTools(server) {
     // ──────────────────────────────────────────────────────────────
     server.registerTool("corven_create_task", {
         title: "Create & Fund Task",
-        description: "Create a new task on TaskEscrow, assign a worker, fund it with ETH, " +
-            "and set a deadline. The payment value is sent as msg.value. " +
-            "descriptionHash is typically an IPFS CID pointing to task details.",
+        description: "Creates a direct-hire task and locks payment in escrow in a single transaction.\n" +
+            "USE WHEN: You have a specific worker address and want to hire them directly. Use corven_post_open_task if you want competitive bidding instead.\n" +
+            "REQUIRES: Both client AND worker must be registered with corven_register_agent. Client wallet needs payment amount plus ~0.0003 ETH gas.\n" +
+            "RETURNS: taskId (save this for all subsequent calls), escrow status, deadline, worker address, Basescan link.\n" +
+            "COMES AFTER: corven_find_workers to get the worker address.\n" +
+            "COMES BEFORE: Worker calls corven_submit_work. Client calls corven_verify_task.\n" +
+            "NOTE: Payment is locked — neither party can access it until verification completes.",
         inputSchema: {
-            worker: z.string().describe("Worker agent's Ethereum address"),
-            payment: z.string().describe("Payment amount in ETH, e.g. '0.01'"),
-            deadline: z
-                .number()
-                .describe("Unix timestamp deadline (seconds since epoch)"),
-            descriptionHash: z
-                .string()
-                .describe("IPFS CID or on-chain hash for task description"),
-            priority: z
-                .number()
-                .optional()
-                .describe("Priority level 0-3 (Low/Medium/High/Urgent). Default 1 (Medium)"),
+            worker: ethAddress,
+            payment: ethAmount,
+            deadline: unixDeadline,
+            descriptionHash: ipfsCid,
+            priority: prioritySchema,
         },
     }, async ({ worker, payment, deadline, descriptionHash, priority }) => {
         try {
-            // Validate input
             const validationResult = createTaskSchema.safeParse({ worker, payment, deadline, descriptionHash, priority });
             if (!validationResult.success) {
-                return formatError(new Error(`Invalid input: ${validationResult.error.issues.map((e) => e.message).join(", ")}`));
+                return formatStructuredError("Invalid task parameters.", validationResult.error.issues.map((e) => e.message).join(", "), "Check: worker must be full 42-char 0x address, payment decimal ETH string (0.001-1000), deadline future Unix timestamp, descriptionHash valid IPFS CID.", true);
             }
-            // Validation successful, use validated values
-            const validatedWorker = worker;
-            const validatedPayment = payment;
-            const validatedDeadline = deadline;
-            const validatedDescriptionHash = descriptionHash;
-            const validatedPriority = priority;
             const account = getAccount();
             if (!account) {
-                return formatError(new Error("No private key configured — cannot send transactions"));
+                return formatStructuredError("No private key configured.", "PRIVATE_KEY environment variable is not set.", "Set PRIVATE_KEY in your .env file.", false);
             }
             const paymentWei = parseEther(payment);
             const priorityLevel = priority ?? 1;
-            // Use createAndFundTask which is the combined function used by client.ts
+            // Calculate total value: payment + protocol fee (1%) + priority fee
+            const PROTOCOL_FEE_BPS = 100n; // 1%
+            const PRIORITY_FEES = [50n, 100n, 200n, 500n]; // Low, Medium, High, Urgent
+            const priorityFeeBps = PRIORITY_FEES[priorityLevel] ?? 100n;
+            const totalFeeBps = PROTOCOL_FEE_BPS + priorityFeeBps;
+            const feeAmount = paymentWei * totalFeeBps / 10000n;
+            const totalValue = paymentWei + feeAmount;
             const result = await executeOrPrepare(CONTRACTS.TaskEscrow, ABI, "createAndFundTask", [
-                validatedWorker,
+                worker,
                 paymentWei,
-                BigInt(validatedDeadline),
-                validatedDescriptionHash,
-            ], paymentWei // send ETH as msg.value
-            );
+                BigInt(deadline),
+                descriptionHash,
+            ], totalValue);
+            if (result.status === "success") {
+                const deadlineDate = new Date(deadline * 1000).toUTCString();
+                return formatSuccess(`Task created. ${payment} ETH locked in escrow for worker.`, {
+                    worker,
+                    client: account,
+                    payment: `${payment} ETH`,
+                    deadline: deadlineDate,
+                    specificationIpfs: descriptionHash,
+                    status: "Funded",
+                    priority: priorityLevel,
+                }, result.txHash, [
+                    "Wait for worker to call corven_submit_work with your taskId.",
+                    "Then call corven_verify_task to release payment after reviewing work.",
+                    "Check status anytime with corven_get_task.",
+                ]);
+            }
             return formatTxResult(result);
         }
         catch (e) {
-            return formatError(e);
+            const parsed = parseContractError(e);
+            return formatStructuredError(parsed.error, parsed.cause, parsed.fix, parsed.retryable);
         }
     });
     // ──────────────────────────────────────────────────────────────
@@ -108,23 +122,22 @@ export function registerEscrowTools(server) {
     // ──────────────────────────────────────────────────────────────
     server.registerTool("corven_get_task", {
         title: "Get Task Details",
-        description: "Retrieve full on-chain details for a task by its numeric ID. " +
-            "Returns client, worker, payment, deadline, status (human-readable), hashes, and timestamps.",
+        description: "Returns complete details for any task including current lifecycle status.\n" +
+            "USE WHEN: Checking if a worker has submitted work. Confirming payment released. Getting deliverable IPFS hash. Checking deadline.\n" +
+            "REQUIRES: Nothing. Free read-only call.\n" +
+            "RETURNS: Status, client/worker addresses, payment, deadline, specification hash, deliverable hash.\n" +
+            "STATUS MEANINGS: Funded=worker can begin. InProgress=worker acknowledged. Submitted=work ready for review. Completed=paid. Failed=rejected or expired.",
         inputSchema: {
-            taskId: z.number().describe("Numeric task ID"),
+            taskId: taskIdSchema,
         },
     }, async ({ taskId }) => {
         try {
-            // Validate input
-            const taskIdParam = taskId;
-            const validationResult = getTaskSchema.safeParse({ taskId: taskIdParam });
+            const validationResult = getTaskSchema.safeParse({ taskId });
             if (!validationResult.success) {
-                return formatError(new Error(`Invalid input: ${validationResult.error.issues.map((e) => e.message).join(", ")}`));
+                return formatStructuredError("Invalid task ID.", `Received '${taskId}' — must be a positive integer.`, "Pass the numeric taskId returned by corven_create_task. Find your task IDs with corven_get_client_tasks or corven_get_worker_tasks.", false);
             }
-            // Use validated taskId
             const validatedTaskId = validationResult.data.taskId;
             const data = await readContract(CONTRACTS.TaskEscrow, ABI, "getTask", [BigInt(validatedTaskId)]);
-            // Enrich status and priority with human-readable labels
             const enriched = {
                 ...data,
                 statusLabel: TASK_STATUS[data.status] ?? `Unknown(${data.status})`,
@@ -133,7 +146,8 @@ export function registerEscrowTools(server) {
             return formatReadResult(enriched, `Task #${taskId}`);
         }
         catch (e) {
-            return formatError(e);
+            const parsed = parseContractError(e);
+            return formatStructuredError(parsed.error, parsed.cause, parsed.fix, parsed.retryable);
         }
     });
     // ──────────────────────────────────────────────────────────────
@@ -141,33 +155,35 @@ export function registerEscrowTools(server) {
     // ──────────────────────────────────────────────────────────────
     server.registerTool("corven_submit_work", {
         title: "Submit Work Deliverable",
-        description: "Worker submits a deliverable hash (typically IPFS CID) for a task. " +
-            "Only the assigned worker can call this. Transitions task status to Submitted.",
+        description: "Worker submits completed deliverable IPFS hash on-chain. Commits work permanently and notifies the client.\n" +
+            "USE WHEN: You are the worker and have finished executing the task. Upload deliverable to IPFS first. Then call this with the CID.\n" +
+            "REQUIRES: You must be the assigned worker. Task status must be Funded or InProgress. Deadline must not have passed.\n" +
+            "RETURNS: Submission confirmation, IPFS hash recorded on-chain, next action for the client.\n" +
+            "COMES AFTER: Worker executes task off-chain and uploads deliverable to IPFS.\n" +
+            "COMES BEFORE: Client calls corven_verify_task.",
         inputSchema: {
-            taskId: z.number().describe("Numeric task ID"),
-            deliverableHash: z
-                .string()
-                .describe("IPFS CID or hash of the deliverable"),
+            taskId: taskIdSchema,
+            deliverableHash: ipfsCid,
         },
     }, async ({ taskId, deliverableHash }) => {
         try {
-            // Validate input
             const validationResult = submitWorkSchema.safeParse({ taskId, deliverableHash });
             if (!validationResult.success) {
-                return formatError(new Error(`Invalid input: ${validationResult.error.issues.map((e) => e.message).join(", ")}`));
+                return formatStructuredError("Invalid parameters.", validationResult.error.issues.map((e) => e.message).join(", "), "taskId must be a positive integer. deliverableHash must be a valid IPFS CID (Qm... or bafy...).", true);
             }
-            // Use validated values
-            const validatedTaskId = validationResult.data.taskId;
-            const validatedDeliverableHash = validationResult.data.deliverableHash;
             const account = getAccount();
             if (!account) {
-                return formatError(new Error("No private key configured — cannot send transactions"));
+                return formatStructuredError("No private key configured.", "PRIVATE_KEY not set.", "Set PRIVATE_KEY in .env.", false);
+            }
+            const result = await executeOrPrepare(CONTRACTS.TaskEscrow, ABI, "submitWork", [BigInt(taskId), deliverableHash]);
+            if (result.status === "success") {
+                return formatSuccess(`Work submitted for Task #${taskId}. Client will be notified.`, { taskId, deliverableHash, status: "Submitted" }, result.txHash, ["Wait for client to review and call corven_verify_task.", "Payment releases automatically on approval."]);
             }
-            const result = await executeOrPrepare(CONTRACTS.TaskEscrow, ABI, "submitWork", [BigInt(validatedTaskId), validatedDeliverableHash]);
             return formatTxResult(result);
         }
         catch (e) {
-            return formatError(e);
+            const parsed = parseContractError(e);
+            return formatStructuredError(parsed.error, parsed.cause, parsed.fix, parsed.retryable);
         }
     });
     // ──────────────────────────────────────────────────────────────
@@ -175,30 +191,39 @@ export function registerEscrowTools(server) {
     // ──────────────────────────────────────────────────────────────
     server.registerTool("corven_verify_task", {
         title: "Verify & Approve Task",
-        description: "Client verifies a submitted task and releases payment to the worker. " +
-            "Only the task client can call this. Transitions status to Completed.",
+        description: "Client approves submitted work. Triggers automatic payment release. Worker receives ETH. Reputation updates. ERC-8004 receipt created.\n" +
+            "USE WHEN: You are the client. Worker has submitted work (corven_get_task shows status Submitted). You have reviewed and approve.\n" +
+            "REQUIRES: You must be the client. Task status must be Submitted. Call corven_dispute_task instead to reject.\n" +
+            "RETURNS: Payment release confirmation, new reputation scores for both agents, receipt ID, Basescan link.\n" +
+            "COMES AFTER: corven_submit_work by the worker.\n" +
+            "NOTE: This is the final step. Payment releases automatically — no manual transfer needed.",
         inputSchema: {
-            taskId: z.number().describe("Numeric task ID"),
-            success: z.boolean().describe("Whether the task passed verification (true = approved, false = rejected)"),
+            taskId: taskIdSchema,
+            success: z.boolean().describe("true = approve work and release payment, false = reject work and refund client"),
         },
     }, async ({ taskId, success }) => {
         try {
-            // Validate input
             const validationResult = verifyTaskSchema.safeParse({ taskId, success });
             if (!validationResult.success) {
-                return formatError(new Error(`Invalid input: ${validationResult.error.issues.map((e) => e.message).join(", ")}`));
+                return formatStructuredError("Invalid parameters.", validationResult.error.issues.map((e) => e.message).join(", "), "taskId must be positive integer. success must be boolean.", true);
             }
-            // Use validated values
-            const { taskId: validatedTaskId, success: validatedSuccess } = validationResult.data;
             const account = getAccount();
             if (!account) {
-                return formatError(new Error("No private key configured — cannot send transactions"));
+                return formatStructuredError("No private key configured.", "PRIVATE_KEY not set.", "Set PRIVATE_KEY in .env.", false);
+            }
+            const result = await executeOrPrepare(CONTRACTS.TaskEscrow, ABI, "verifyTask", [BigInt(taskId), success], undefined, "TaskEscrow");
+            if (result.status === "success") {
+                return formatSuccess(success
+                    ? `Task #${taskId} approved. Payment released to worker automatically.`
+                    : `Task #${taskId} rejected. Payment refunded to client.`, { taskId, verdict: success ? "APPROVED" : "REJECTED" }, result.txHash, success
+                    ? ["Payment has been transferred to the worker's wallet.", "Both agents' reputation scores have been updated.", "An ERC-8004 receipt has been created as permanent proof."]
+                    : ["Payment has been refunded to your wallet.", "Worker's reputation has been penalized."]);
             }
-            const result = await executeOrPrepare(CONTRACTS.TaskEscrow, ABI, "verifyTask", [BigInt(validatedTaskId), validatedSuccess], undefined, "TaskEscrow");
             return formatTxResult(result);
         }
         catch (e) {
-            return formatError(e);
+            const parsed = parseContractError(e);
+            return formatStructuredError(parsed.error, parsed.cause, parsed.fix, parsed.retryable);
         }
     });
     // ──────────────────────────────────────────────────────────────
@@ -206,34 +231,30 @@ export function registerEscrowTools(server) {
     // ──────────────────────────────────────────────────────────────
     server.registerTool("corven_dispute_task", {
         title: "Dispute a Task",
-        description: "Open a dispute on a task. Either the client or worker can dispute. " +
-            "Transitions status to Disputed and pauses payment release.",
+        description: "Freezes a task and initiates jury-based dispute resolution. Three randomly-selected agents vote. Majority decides.\n" +
+            "USE WHEN: You are the client and submitted work clearly fails the specification. Or you are the worker and were unfairly rejected.\n" +
+            "REQUIRES: Task status must be Submitted. Either client or worker can call.\n" +
+            "RETURNS: Dispute ID, jury selection confirmation, voting deadline.\n" +
+            "NOTE: Call corven_get_task first to confirm the task is in Submitted status.",
         inputSchema: {
-            taskId: z.number().describe("Numeric task ID"),
-            reason: z
-                .string()
-                .optional()
-                .describe("Optional reason for the dispute (stored off-chain / emitted in event)"),
+            taskId: taskIdSchema,
+            reason: z.string().max(500).optional().describe("Optional reason for the dispute"),
         },
     }, async ({ taskId, reason }) => {
         try {
-            // Validate input
-            const validationResult = disputeTaskSchema.safeParse({ taskId, reason });
-            if (!validationResult.success) {
-                return formatError(new Error(`Invalid input: ${validationResult.error.issues.map((e) => e.message).join(", ")}`));
-            }
-            // Use validated values
-            const validatedTaskId = validationResult.data.taskId;
-            const validatedReason = validationResult.data.reason;
             const account = getAccount();
             if (!account) {
-                return formatError(new Error("No private key configured — cannot send transactions"));
+                return formatStructuredError("No private key configured.", "PRIVATE_KEY not set.", "Set PRIVATE_KEY in .env.", false);
+            }
+            const result = await executeOrPrepare(CONTRACTS.TaskEscrow, ABI, "disputeTask", [BigInt(taskId)], undefined, "TaskEscrow");
+            if (result.status === "success") {
+                return formatSuccess(`Task #${taskId} disputed. Payment frozen pending jury resolution.`, { taskId, reason: reason || "No reason provided", status: "Disputed" }, result.txHash, ["Three jurors will be randomly selected to vote.", "Resolution typically takes 24-48 hours."]);
             }
-            const result = await executeOrPrepare(CONTRACTS.TaskEscrow, ABI, "disputeTask", [BigInt(validatedTaskId)], undefined, "TaskEscrow");
             return formatTxResult(result);
         }
         catch (e) {
-            return formatError(e);
+            const parsed = parseContractError(e);
+            return formatStructuredError(parsed.error, parsed.cause, parsed.fix, parsed.retryable);
         }
     });
     // ──────────────────────────────────────────────────────────────
@@ -241,26 +262,39 @@ export function registerEscrowTools(server) {
     // ──────────────────────────────────────────────────────────────
     server.registerTool("corven_create_task_with_priority", {
         title: "Create Task with Priority",
-        description: "Create a task with a specific priority level (0=Low, 1=Medium, 2=High, 3=Urgent). " +
-            "Higher priority incurs additional protocol fees.",
+        description: "Creates a direct-hire task with a specific priority level and locks payment in escrow.\n" +
+            "USE WHEN: You have a specific worker and need urgent or high-priority execution with guaranteed faster attention.\n" +
+            "REQUIRES: Both client AND worker registered. Client wallet needs payment + priority fee + ~0.0003 ETH gas.\n" +
+            "RETURNS: taskId, escrow status, priority level, total cost breakdown, Basescan link.\n" +
+            "COMES AFTER: corven_find_workers to get the worker address.\n" +
+            "COMES BEFORE: Worker calls corven_submit_work. Client calls corven_verify_task.\n" +
+            "NOTE: Priority fees — Low: 0.5%, Medium: 1%, High: 2%, Urgent: 5%. Use corven_create_task for default Medium priority.",
         inputSchema: {
-            worker: z.string().describe("Worker agent's Ethereum address"),
-            payment: z.string().describe("Payment amount in ETH"),
-            deadline: z.number().describe("Unix timestamp deadline (seconds)"),
-            descriptionHash: z.string().describe("IPFS CID for task description"),
-            priority: z.number().describe("Priority level: 0=Low, 1=Medium, 2=High, 3=Urgent"),
+            worker: ethAddress,
+            payment: ethAmount,
+            deadline: unixDeadline,
+            descriptionHash: ipfsCid,
+            priority: prioritySchema,
         },
     }, async ({ worker, payment, deadline, descriptionHash, priority }) => {
         try {
             const account = getAccount();
             if (!account)
-                return formatError(new Error("No private key configured"));
+                return formatStructuredError("No private key configured.", "PRIVATE_KEY not set.", "Set PRIVATE_KEY in .env.", false);
             const paymentWei = parseEther(payment);
-            const result = await executeOrPrepare(CONTRACTS.TaskEscrow, ABI, "createAndFundTaskWithPriority", [worker, paymentWei, BigInt(deadline), descriptionHash, priority], paymentWei);
+            // Calculate total value: payment + protocol fee (1%) + priority fee
+            const PROTOCOL_FEE_BPS = 100n;
+            const PRIORITY_FEES = [50n, 100n, 200n, 500n];
+            const priorityFeeBps = PRIORITY_FEES[priority] ?? 100n;
+            const totalFeeBps = PROTOCOL_FEE_BPS + priorityFeeBps;
+            const feeAmount = paymentWei * totalFeeBps / 10000n;
+            const totalValue = paymentWei + feeAmount;
+            const result = await executeOrPrepare(CONTRACTS.TaskEscrow, ABI, "createAndFundTaskWithPriority", [worker, paymentWei, BigInt(deadline), descriptionHash, priority], totalValue);
             return formatTxResult(result);
         }
         catch (e) {
-            return formatError(e);
+            const p = parseContractError(e);
+            return formatStructuredError(p.error, p.cause, p.fix, p.retryable);
         }
     });
     // ──────────────────────────────────────────────────────────────
@@ -268,13 +302,18 @@ export function registerEscrowTools(server) {
     // ──────────────────────────────────────────────────────────────
     server.registerTool("corven_create_milestone_task", {
         title: "Create Milestone Task",
-        description: "Create a task with milestone-based payments. Each milestone has its own description and payment amount. " +
-            "Total payment = sum of all milestone payments.",
+        description: "Creates a task with incremental milestone-based payments. Each milestone is verified and paid independently.\n" +
+            "USE WHEN: Task has distinct phases (e.g., research, draft, final). You want partial payment tied to checkpoints.\n" +
+            "REQUIRES: Both client AND worker registered. Client wallet needs totalPayment + ~2% fees + ~0.0003 ETH gas.\n" +
+            "RETURNS: taskId, milestone count, individual milestone amounts, total escrowed, Basescan link.\n" +
+            "COMES AFTER: corven_find_workers to get the worker address.\n" +
+            "COMES BEFORE: Worker calls corven_submit_milestone per milestone. Client calls corven_verify_milestone to release each payment.\n" +
+            "NOTE: totalPayment must equal the sum of milestonePayments. Milestones are verified in order (0, 1, 2, ...).",
         inputSchema: {
-            worker: z.string().describe("Worker agent's Ethereum address"),
-            totalPayment: z.string().describe("Total payment in ETH (sum of milestones)"),
-            deadline: z.number().describe("Unix timestamp deadline"),
-            descriptionHash: z.string().describe("IPFS CID for task description"),
+            worker: ethAddress,
+            totalPayment: ethAmount,
+            deadline: unixDeadline,
+            descriptionHash: ipfsCid,
             milestoneDescriptions: z.array(z.string()).describe("Array of milestone descriptions"),
             milestonePayments: z.array(z.string()).describe("Array of milestone payments in ETH"),
         },
@@ -282,14 +321,21 @@ export function registerEscrowTools(server) {
         try {
             const account = getAccount();
             if (!account)
-                return formatError(new Error("No private key configured"));
+                return formatStructuredError("No private key configured.", "PRIVATE_KEY not set.", "Set PRIVATE_KEY in .env.", false);
             const paymentWei = parseEther(totalPayment);
             const payments = milestonePayments.map(p => parseEther(p));
-            const result = await executeOrPrepare(CONTRACTS.TaskEscrow, ABI, "createTaskWithMilestones", [worker, paymentWei, BigInt(deadline), descriptionHash, milestoneDescriptions, payments], paymentWei);
+            // Calculate total value: payment + protocol fee (1%) + priority fee (default Medium=1%)
+            const PROTOCOL_FEE_BPS = 100n;
+            const PRIORITY_FEE_BPS = 100n; // Default Medium priority
+            const totalFeeBps = PROTOCOL_FEE_BPS + PRIORITY_FEE_BPS;
+            const feeAmount = paymentWei * totalFeeBps / 10000n;
+            const totalValue = paymentWei + feeAmount;
+            const result = await executeOrPrepare(CONTRACTS.TaskEscrow, ABI, "createTaskWithMilestones", [worker, paymentWei, BigInt(deadline), descriptionHash, milestoneDescriptions, payments], totalValue);
             return formatTxResult(result);
         }
         catch (e) {
-            return formatError(e);
+            const p = parseContractError(e);
+            return formatStructuredError(p.error, p.cause, p.fix, p.retryable);
         }
     });
     // ──────────────────────────────────────────────────────────────
@@ -297,22 +343,29 @@ export function registerEscrowTools(server) {
     // ──────────────────────────────────────────────────────────────
     server.registerTool("corven_submit_milestone", {
         title: "Submit Milestone",
-        description: "Submit a deliverable for a specific milestone in a milestone-based task.",
+        description: "Worker submits a deliverable for a specific milestone in a milestone-based task.\n" +
+            "USE WHEN: You are the worker and have completed one milestone phase. Upload deliverable to IPFS first.\n" +
+            "REQUIRES: You must be the assigned worker. Milestone must not already be submitted. Task status must be Funded or InProgress.\n" +
+            "RETURNS: Submission confirmation, milestone index, IPFS hash recorded on-chain.\n" +
+            "COMES AFTER: corven_create_milestone_task created the task with milestones.\n" +
+            "COMES BEFORE: Client calls corven_verify_milestone to approve and release payment for this milestone.\n" +
+            "NOTE: Milestones must be submitted in order. You cannot skip ahead.",
         inputSchema: {
-            taskId: z.number().describe("Task ID"),
+            taskId: taskIdSchema,
             milestoneIndex: z.number().describe("Milestone index (0-based)"),
-            deliverableHash: z.string().describe("IPFS CID of milestone deliverable"),
+            deliverableHash: ipfsCid,
         },
     }, async ({ taskId, milestoneIndex, deliverableHash }) => {
         try {
             const account = getAccount();
             if (!account)
-                return formatError(new Error("No private key configured"));
+                return formatStructuredError("No private key configured.", "PRIVATE_KEY not set.", "Set PRIVATE_KEY in .env.", false);
             const result = await executeOrPrepare(CONTRACTS.TaskEscrow, ABI, "submitMilestone", [BigInt(taskId), BigInt(milestoneIndex), deliverableHash]);
             return formatTxResult(result);
         }
         catch (e) {
-            return formatError(e);
+            const p = parseContractError(e);
+            return formatStructuredError(p.error, p.cause, p.fix, p.retryable);
         }
     });
     // ──────────────────────────────────────────────────────────────
@@ -320,9 +373,15 @@ export function registerEscrowTools(server) {
     // ──────────────────────────────────────────────────────────────
     server.registerTool("corven_verify_milestone", {
         title: "Verify Milestone",
-        description: "Verify a submitted milestone and release its payment to the worker.",
+        description: "Client verifies a submitted milestone and releases its payment to the worker.\n" +
+            "USE WHEN: You are the client. Worker has submitted a milestone (corven_get_milestone shows submitted). You have reviewed and approve.\n" +
+            "REQUIRES: You must be the client. Milestone must have been submitted by the worker.\n" +
+            "RETURNS: Verification result, payment released amount, milestone status update.\n" +
+            "COMES AFTER: corven_submit_milestone by the worker.\n" +
+            "COMES BEFORE: Next milestone submission, or task completion if this was the final milestone.\n" +
+            "NOTE: Rejecting a milestone does not refund the entire task — only that milestone's payment is withheld.",
         inputSchema: {
-            taskId: z.number().describe("Task ID"),
+            taskId: taskIdSchema,
             milestoneIndex: z.number().describe("Milestone index (0-based)"),
             success: z.boolean().describe("Whether the milestone passes verification"),
         },
@@ -330,47 +389,42 @@ export function registerEscrowTools(server) {
         try {
             const account = getAccount();
             if (!account)
-                return formatError(new Error("No private key configured"));
+                return formatStructuredError("No private key configured.", "PRIVATE_KEY not set.", "Set PRIVATE_KEY in .env.", false);
             const result = await executeOrPrepare(CONTRACTS.TaskEscrow, ABI, "verifyMilestone", [BigInt(taskId), BigInt(milestoneIndex), success], undefined, "TaskEscrow");
             return formatTxResult(result);
         }
         catch (e) {
-            return formatError(e);
+            const p = parseContractError(e);
+            return formatStructuredError(p.error, p.cause, p.fix, p.retryable);
         }
     });
     // ──────────────────────────────────────────────────────────────
-    // corven_get_milestone
+    // corven_get_milestone (includes count when no index provided)
     // ──────────────────────────────────────────────────────────────
     server.registerTool("corven_get_milestone", {
-        title: "Get Milestone Details",
-        description: "Retrieve details of a specific milestone in a task.",
+        title: "Get Milestone",
+        description: "Reads milestone details by index, or returns the total milestone count if no index is provided.\n" +
+            "USE WHEN: Checking which milestones have been submitted or verified. Counting milestones before submission.\n" +
+            "REQUIRES: Nothing. Free read-only call.\n" +
+            "RETURNS: Milestone description, payment amount, submission hash, verification status — or milestone count if index omitted.\n" +
+            "COMES AFTER: corven_create_milestone_task created the task.\n" +
+            "COMES BEFORE: corven_submit_milestone or corven_verify_milestone.",
         inputSchema: {
-            taskId: z.number().describe("Task ID"),
-            milestoneIndex: z.number().describe("Milestone index (0-based)"),
+            taskId: taskIdSchema,
+            milestoneIndex: z.number().optional().describe("Milestone index (0-based). Omit to get count."),
         },
     }, async ({ taskId, milestoneIndex }) => {
         try {
+            if (milestoneIndex === undefined) {
+                const count = await readContract(CONTRACTS.TaskEscrow, ABI, "getMilestoneCount", [BigInt(taskId)]);
+                return formatReadResult({ taskId, milestoneCount: Number(count) }, `Milestone count for Task #${taskId}`);
+            }
             const data = await readContract(CONTRACTS.TaskEscrow, ABI, "getMilestone", [BigInt(taskId), BigInt(milestoneIndex)]);
             return formatReadResult(data, `Milestone ${milestoneIndex} of Task #${taskId}`);
         }
         catch (e) {
-            return formatError(e);
-        }
-    });
-    // ──────────────────────────────────────────────────────────────
-    // corven_get_milestone_count
-    // ──────────────────────────────────────────────────────────────
-    server.registerTool("corven_get_milestone_count", {
-        title: "Get Milestone Count",
-        description: "Get the number of milestones in a task.",
-        inputSchema: { taskId: z.number().describe("Task ID") },
-    }, async ({ taskId }) => {
-        try {
-            const count = await readContract(CONTRACTS.TaskEscrow, ABI, "getMilestoneCount", [BigInt(taskId)]);
-            return formatReadResult({ taskId, milestoneCount: Number(count) }, `Milestones for Task #${taskId}`);
-        }
-        catch (e) {
-            return formatError(e);
+            const p = parseContractError(e);
+            return formatStructuredError(p.error, p.cause, p.fix, p.retryable);
         }
     });
     // ──────────────────────────────────────────────────────────────
@@ -378,25 +432,38 @@ export function registerEscrowTools(server) {
     // ──────────────────────────────────────────────────────────────
     server.registerTool("corven_create_subtask", {
         title: "Create Subtask",
-        description: "Create a child task under a parent task. The subtask has its own worker and payment.",
+        description: "Creates a child task under a parent task with its own worker, payment, and deadline.\n" +
+            "USE WHEN: Decomposing a large task into parallel subtasks for different specialists.\n" +
+            "REQUIRES: Parent task must exist. Both client and subtask worker must be registered. Client wallet needs payment + ~2% fees.\n" +
+            "RETURNS: Subtask taskId, parent reference, worker, payment, deadline.\n" +
+            "COMES AFTER: corven_create_task created the parent task.\n" +
+            "COMES BEFORE: Subtask worker calls corven_submit_work. Client calls corven_verify_task on the subtask.\n" +
+            "NOTE: Subtask payment is funded independently from the parent. Use corven_get_child_tasks to list all subtasks.",
         inputSchema: {
-            parentTaskId: z.number().describe("Parent task ID"),
-            worker: z.string().describe("Worker address for the subtask"),
-            payment: z.string().describe("Payment in ETH"),
-            deadline: z.number().describe("Unix timestamp deadline"),
-            descriptionHash: z.string().describe("IPFS CID for subtask description"),
+            parentTaskId: taskIdSchema,
+            worker: ethAddress,
+            payment: ethAmount,
+            deadline: unixDeadline,
+            descriptionHash: ipfsCid,
         },
     }, async ({ parentTaskId, worker, payment, deadline, descriptionHash }) => {
         try {
             const account = getAccount();
             if (!account)
-                return formatError(new Error("No private key configured"));
+                return formatStructuredError("No private key configured.", "PRIVATE_KEY not set.", "Set PRIVATE_KEY in .env.", false);
             const paymentWei = parseEther(payment);
-            const result = await executeOrPrepare(CONTRACTS.TaskEscrow, ABI, "createSubtask", [BigInt(parentTaskId), worker, paymentWei, BigInt(deadline), descriptionHash], paymentWei);
+            // Calculate total value: payment + protocol fee (1%) + priority fee (default Medium=1%)
+            const PROTOCOL_FEE_BPS = 100n;
+            const PRIORITY_FEE_BPS = 100n;
+            const totalFeeBps = PROTOCOL_FEE_BPS + PRIORITY_FEE_BPS;
+            const feeAmount = paymentWei * totalFeeBps / 10000n;
+            const totalValue = paymentWei + feeAmount;
+            const result = await executeOrPrepare(CONTRACTS.TaskEscrow, ABI, "createSubtask", [BigInt(parentTaskId), worker, paymentWei, BigInt(deadline), descriptionHash], totalValue);
             return formatTxResult(result);
         }
         catch (e) {
-            return formatError(e);
+            const p = parseContractError(e);
+            return formatStructuredError(p.error, p.cause, p.fix, p.retryable);
         }
     });
     // ──────────────────────────────────────────────────────────────
@@ -404,15 +471,21 @@ export function registerEscrowTools(server) {
     // ──────────────────────────────────────────────────────────────
     server.registerTool("corven_get_child_tasks", {
         title: "Get Child Tasks",
-        description: "Get the IDs of all child tasks under a parent task.",
-        inputSchema: { parentTaskId: z.number().describe("Parent task ID") },
+        description: "Returns the IDs of all child tasks (subtasks) under a parent task.\n" +
+            "USE WHEN: Tracking progress of decomposed tasks. Checking if all subtasks are complete before parent verification.\n" +
+            "REQUIRES: Nothing. Free read-only call.\n" +
+            "RETURNS: Parent task ID, child count, array of child task IDs.\n" +
+            "COMES AFTER: corven_create_subtask created child tasks.\n" +
+            "COMES BEFORE: Use corven_get_task on each child ID to check individual status.",
+        inputSchema: { parentTaskId: taskIdSchema },
     }, async ({ parentTaskId }) => {
         try {
             const childIds = await readContract(CONTRACTS.TaskEscrow, ABI, "getChildTasks", [BigInt(parentTaskId)]);
             return formatReadResult({ parentTaskId, childCount: childIds.length, childTaskIds: childIds }, `Child tasks of Task #${parentTaskId}`);
         }
         catch (e) {
-            return formatError(e);
+            const p = parseContractError(e);
+            return formatStructuredError(p.error, p.cause, p.fix, p.retryable);
         }
     });
     // ──────────────────────────────────────────────────────────────
@@ -420,9 +493,15 @@ export function registerEscrowTools(server) {
     // ──────────────────────────────────────────────────────────────
     server.registerTool("corven_submit_query", {
         title: "Submit Task Query",
-        description: "Submit a query about a task during execution. Allows workers to ask clarifying questions.",
+        description: "Worker submits a clarifying question about a task during execution. The query is recorded on-chain.\n" +
+            "USE WHEN: Task specification is ambiguous. You need additional resources. You want to confirm feasibility before proceeding.\n" +
+            "REQUIRES: You must be the assigned worker. Task must be in Funded or InProgress status.\n" +
+            "RETURNS: Query ID, task ID, query type, submission confirmation.\n" +
+            "COMES AFTER: corven_create_task assigned you the task.\n" +
+            "COMES BEFORE: Client calls corven_respond_to_query. Then you continue work.\n" +
+            "NOTE: Query types: 0=Specification (unclear requirements), 1=Resource (need more time/data), 2=Feasibility (concern about viability).",
         inputSchema: {
-            taskId: z.number().describe("Task ID"),
+            taskId: taskIdSchema,
             queryText: z.string().describe("The query text"),
             queryType: z.number().describe("Query type: 0=Specification, 1=Resource, 2=Feasibility"),
         },
@@ -430,12 +509,13 @@ export function registerEscrowTools(server) {
         try {
             const account = getAccount();
             if (!account)
-                return formatError(new Error("No private key configured"));
+                return formatStructuredError("No private key configured.", "PRIVATE_KEY not set.", "Set PRIVATE_KEY in .env.", false);
             const result = await executeOrPrepare(CONTRACTS.TaskEscrow, ABI, "submitQuery", [BigInt(taskId), queryText, queryType]);
             return formatTxResult(result);
         }
         catch (e) {
-            return formatError(e);
+            const p = parseContractError(e);
+            return formatStructuredError(p.error, p.cause, p.fix, p.retryable);
         }
     });
     // ──────────────────────────────────────────────────────────────
@@ -443,88 +523,83 @@ export function registerEscrowTools(server) {
     // ──────────────────────────────────────────────────────────────
     server.registerTool("corven_respond_to_query", {
         title: "Respond to Query",
-        description: "Respond to a worker's query about a task. Only the task client can respond.",
+        description: "Client responds to a worker's clarifying query about a task. Response is recorded on-chain.\n" +
+            "USE WHEN: A worker has submitted a query (corven_get_query shows pending queries). You want to provide clarification.\n" +
+            "REQUIRES: You must be the task client. A query must exist on the task.\n" +
+            "RETURNS: Response confirmation, task ID, response text recorded.\n" +
+            "COMES AFTER: corven_submit_query by the worker.\n" +
+            "COMES BEFORE: Worker continues task execution with your clarification.\n" +
+            "NOTE: Check query details first with corven_get_query to understand what the worker is asking.",
         inputSchema: {
-            taskId: z.number().describe("Task ID"),
+            taskId: taskIdSchema,
             responseText: z.string().describe("The response text"),
         },
     }, async ({ taskId, responseText }) => {
         try {
             const account = getAccount();
             if (!account)
-                return formatError(new Error("No private key configured"));
+                return formatStructuredError("No private key configured.", "PRIVATE_KEY not set.", "Set PRIVATE_KEY in .env.", false);
             const result = await executeOrPrepare(CONTRACTS.TaskEscrow, ABI, "respondToQuery", [BigInt(taskId), responseText]);
             return formatTxResult(result);
         }
         catch (e) {
-            return formatError(e);
+            const p = parseContractError(e);
+            return formatStructuredError(p.error, p.cause, p.fix, p.retryable);
         }
     });
     // ──────────────────────────────────────────────────────────────
-    // corven_get_query
+    // corven_get_query (includes count when no queryId provided)
     // ──────────────────────────────────────────────────────────────
     server.registerTool("corven_get_query", {
-        title: "Get Query Details",
-        description: "Retrieve details of a specific query on a task.",
+        title: "Get Query",
+        description: "Reads query details by index, or returns the total query count if no index is provided.\n" +
+            "USE WHEN: Checking if a worker has submitted questions. Reading query text before responding. Counting outstanding queries.\n" +
+            "REQUIRES: Nothing. Free read-only call.\n" +
+            "RETURNS: Query text, type (Specification/Resource/Feasibility), response status — or query count if index omitted.\n" +
+            "COMES AFTER: corven_submit_query created a query.\n" +
+            "COMES BEFORE: corven_respond_to_query to provide an answer.",
         inputSchema: {
-            taskId: z.number().describe("Task ID"),
-            queryId: z.number().describe("Query index (0-based)"),
+            taskId: taskIdSchema,
+            queryId: z.number().optional().describe("Query index (0-based). Omit to get count."),
         },
     }, async ({ taskId, queryId }) => {
         try {
+            if (queryId === undefined) {
+                const count = await readContract(CONTRACTS.TaskEscrow, ABI, "getQueryCount", [BigInt(taskId)]);
+                return formatReadResult({ taskId, queryCount: Number(count) }, `Query count for Task #${taskId}`);
+            }
             const data = await readContract(CONTRACTS.TaskEscrow, ABI, "getQuery", [BigInt(taskId), BigInt(queryId)]);
             return formatReadResult(data, `Query ${queryId} on Task #${taskId}`);
         }
         catch (e) {
-            return formatError(e);
-        }
-    });
-    // ──────────────────────────────────────────────────────────────
-    // corven_get_query_count
-    // ──────────────────────────────────────────────────────────────
-    server.registerTool("corven_get_query_count", {
-        title: "Get Query Count",
-        description: "Get the number of queries submitted on a task.",
-        inputSchema: { taskId: z.number().describe("Task ID") },
-    }, async ({ taskId }) => {
-        try {
-            const count = await readContract(CONTRACTS.TaskEscrow, ABI, "getQueryCount", [BigInt(taskId)]);
-            return formatReadResult({ taskId, queryCount: Number(count) }, `Queries on Task #${taskId}`);
-        }
-        catch (e) {
-            return formatError(e);
+            const p = parseContractError(e);
+            return formatStructuredError(p.error, p.cause, p.fix, p.retryable);
         }
     });
     // ──────────────────────────────────────────────────────────────
-    // corven_get_client_tasks
+    // corven_get_tasks (consolidated: client, worker, or child tasks)
     // ──────────────────────────────────────────────────────────────
-    server.registerTool("corven_get_client_tasks", {
-        title: "Get Client Tasks",
-        description: "Get all task IDs where the given address is the client.",
-        inputSchema: { client: z.string().describe("Client's Ethereum address") },
-    }, async ({ client }) => {
-        try {
-            const taskIds = await readContract(CONTRACTS.TaskEscrow, ABI, "getClientTasks", [client]);
-            return formatReadResult({ client, taskCount: taskIds.length, taskIds }, `Tasks by client ${client}`);
-        }
-        catch (e) {
-            return formatError(e);
-        }
-    });
-    // ──────────────────────────────────────────────────────────────
-    // corven_get_worker_tasks
-    // ──────────────────────────────────────────────────────────────
-    server.registerTool("corven_get_worker_tasks", {
-        title: "Get Worker Tasks",
-        description: "Get all task IDs where the given address is the worker.",
-        inputSchema: { worker: z.string().describe("Worker's Ethereum address") },
-    }, async ({ worker }) => {
+    server.registerTool("corven_get_tasks", {
+        title: "Get Tasks",
+        description: "Returns all task IDs where the given address is the client or the worker.\n" +
+            "USE WHEN: Finding your active tasks. Checking which tasks you need to work on. Building a task dashboard.\n" +
+            "REQUIRES: Nothing. Free read-only call.\n" +
+            "RETURNS: Address, role, task count, array of task IDs.\n" +
+            "COMES BEFORE: Use corven_get_task on each returned ID to get full details.\n" +
+            "NOTE: Use role='worker' to find tasks assigned to you. Use role='client' to find tasks you posted.",
+        inputSchema: {
+            address: ethAddress,
+            role: z.enum(["client", "worker"]).describe("Filter: 'client' or 'worker'"),
+        },
+    }, async ({ address, role }) => {
         try {
-            const taskIds = await readContract(CONTRACTS.TaskEscrow, ABI, "getWorkerTasks", [worker]);
-            return formatReadResult({ worker, taskCount: taskIds.length, taskIds }, `Tasks by worker ${worker}`);
+            const fn = role === "client" ? "getClientTasks" : "getWorkerTasks";
+            const taskIds = await readContract(CONTRACTS.TaskEscrow, ABI, fn, [address]);
+            return formatReadResult({ address, role, taskCount: taskIds.length, taskIds }, `Tasks where ${address} is ${role}`);
         }
         catch (e) {
-            return formatError(e);
+            const p = parseContractError(e);
+            return formatStructuredError(p.error, p.cause, p.fix, p.retryable);
         }
     });
 }