humanpages 1.4.4 → 1.4.6

package/dist/tools.js

@@ -29,10 +29,30 @@ async function searchHumans(params) {
         query.set('minExperience', params.min_experience.toString());
     if (params.fiat_platform)
         query.set('fiatPlatform', params.fiat_platform);
+    if (params.payment_type)
+        query.set('paymentType', params.payment_type);
+    if (params.accepts_crypto)
+        query.set('acceptsCrypto', 'true');
+    if (params.degree)
+        query.set('degree', params.degree);
+    if (params.field)
+        query.set('field', params.field);
+    if (params.institution)
+        query.set('institution', params.institution);
+    if (params.certificate)
+        query.set('certificate', params.certificate);
+    if (params.min_vouches)
+        query.set('minVouches', params.min_vouches.toString());
+    if (params.has_verified_login)
+        query.set('hasVerifiedLogin', 'true');
+    if (params.has_photo)
+        query.set('hasPhoto', 'true');
     if (params.sort_by)
         query.set('sortBy', params.sort_by);
     if (params.min_completed_jobs)
         query.set('minCompletedJobs', params.min_completed_jobs.toString());
+    if (params.min_channels)
+        query.set('minChannels', params.min_channels.toString());
     const res = await fetch(`${API_BASE}/api/humans/search?${query}`);
     if (!res.ok) {
         throw new Error(`API error: ${res.status}`);
@@ -40,9 +60,18 @@ async function searchHumans(params) {
     return res.json();
 }
 async function getHuman(id) {
-    const res = await fetch(`${API_BASE}/api/humans/${id}`);
+    // Try by ID first, then by username if it looks like one
+    let res = await fetch(`${API_BASE}/api/humans/${encodeURIComponent(id)}`);
+    if (!res.ok && !id.match(/^[0-9a-f-]{36}$/i)) {
+        // Might be a username — sanitize and try the username endpoint
+        const cleanId = id.startsWith('@') ? id.slice(1) : id;
+        if (!/^[a-zA-Z0-9_-]+$/.test(cleanId)) {
+            throw new Error(`Invalid human ID or username: "${id}". Usernames can only contain letters, numbers, hyphens, and underscores. Use search_humans to find valid human IDs.`);
+        }
+        res = await fetch(`${API_BASE}/api/humans/u/${encodeURIComponent(cleanId)}`);
+    }
     if (!res.ok) {
-        throw new Error(`Human not found: ${id}`);
+        throw new Error(`Human not found: "${id}". Use search_humans to find valid human IDs, or try a username (e.g., "johndoe" or "@johndoe").`);
     }
     return res.json();
 }
@@ -59,7 +88,7 @@ export function createServer() {
         tools: [
             {
                 name: 'search_humans',
-                description: 'Search for humans available for hire. All filters are optional — you can combine any of them or use just one. IMPORTANT: When the user wants workers with platform experience or completed jobs, use min_completed_jobs=1 (no skill filter needed) to find ALL humans with completed jobs across any skill. Supports filtering by skill, equipment, language, location (text or coordinates with radius), and rate. Use sort_by to control result ordering — "completed_jobs" (default) surfaces workers with proven platform experience first, "rating" sorts by reviews, "experience" by years of professional experience. When using text location, provide a fully-qualified name (e.g., "Richmond, Virginia, USA" not just "Richmond") for accurate geocoding. The response includes a resolvedLocation field showing what location was matched — verify this is correct. Default search radius is 30km. Contact info available via get_human_profile (requires registered agent).',
+                description: 'Search for humans available for hire. Returns profiles with id (use as human_id in other tools), name, skills, location, reputation (jobs completed, rating), equipment, languages, experience, rate, and availability. All filters are optional — combine any or use none to browse. Key filters: skill (e.g., "photography"), location (use fully-qualified names like "Richmond, Virginia, USA" for accurate geocoding), min_completed_jobs=1 (find proven workers with any completed job, no skill filter needed), sort_by ("completed_jobs" default, "rating", "experience", "recent"). Default search radius is 30km. Response includes total count and resolvedLocation. Contact info requires get_human_profile (registered agent needed). Typical workflow: search_humans → get_human_profile → create_job_offer.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -118,6 +147,43 @@ export function createServer() {
                             type: 'string',
                             description: 'Filter by fiat payment platform the human accepts (e.g., "WISE", "PAYPAL", "VENMO", "REVOLUT", "CASHAPP", "ZELLE", "MONZO", "N26", "MERCADOPAGO")',
                         },
+                        payment_type: {
+                            type: 'string',
+                            enum: ['UPFRONT', 'ESCROW', 'UPON_COMPLETION'],
+                            description: 'Filter by accepted payment type (UPFRONT, ESCROW, or UPON_COMPLETION)',
+                        },
+                        accepts_crypto: {
+                            type: 'boolean',
+                            description: 'Filter to only show humans who have a crypto wallet set up and can accept USDC payments',
+                        },
+                        degree: {
+                            type: 'string',
+                            description: 'Filter by education degree (e.g., "Bachelor", "MBA", "PhD"). Partial match, case-insensitive.',
+                        },
+                        field: {
+                            type: 'string',
+                            description: 'Filter by field of study (e.g., "Computer Science", "Marketing"). Partial match, case-insensitive.',
+                        },
+                        institution: {
+                            type: 'string',
+                            description: 'Filter by educational institution name (e.g., "MIT", "Oxford"). Partial match, case-insensitive.',
+                        },
+                        certificate: {
+                            type: 'string',
+                            description: 'Filter by certificate name or issuer (e.g., "AWS", "PMP", "Google"). Partial match, case-insensitive.',
+                        },
+                        min_vouches: {
+                            type: 'number',
+                            description: 'Only return humans vouched for by at least this many other users.',
+                        },
+                        has_verified_login: {
+                            type: 'boolean',
+                            description: 'Only return humans who have verified their identity via an OAuth provider (Google, LinkedIn, or GitHub). Does not reveal which provider.',
+                        },
+                        has_photo: {
+                            type: 'boolean',
+                            description: 'Only return humans with an approved profile photo.',
+                        },
                         sort_by: {
                             type: 'string',
                             enum: ['completed_jobs', 'rating', 'experience', 'recent'],
@@ -127,12 +193,16 @@ export function createServer() {
                             type: 'number',
                             description: 'Only return humans who have completed at least this many jobs on the platform. Use min_completed_jobs=1 to find all workers with any platform track record. Works with or without other filters — no skill filter needed.',
                         },
+                        min_channels: {
+                            type: 'number',
+                            description: 'Only return humans with at least this many notification channels active (0-4). Channels: email, telegram, whatsapp, push. Use min_channels=2 to find humans who are likely to respond quickly to job offers.',
+                        },
                     },
                 },
             },
             {
                 name: 'get_human',
-                description: 'Get detailed information about a specific human by their ID, including their bio, skills, and service offerings. Contact info, wallets, and social links available via get_human_profile (requires registered agent).',
+                description: 'Get a human\'s public profile by ID — bio, skills, services, equipment, languages, experience, reputation (jobs completed, rating, reviews), humanity verification status, and rate. Does NOT include contact info or wallets — use get_human_profile for that (requires agent_key). The id can be found in search_humans results.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -146,7 +216,7 @@ export function createServer() {
             },
             {
                 name: 'register_agent',
-                description: 'Register as an agent on Human Pages. Agents are auto-activated on PRO tier (free during launch). Returns an API key that you MUST save and use for all subsequent calls. The API key cannot be retrieved later.',
+                description: 'Register a new agent on Human Pages. Returns an API key (hp_...) that you MUST save — it cannot be retrieved later. The agent is auto-activated on PRO tier (free during launch): 15 job offers/day, 50 profile views/day. Use the API key as agent_key in create_job_offer, get_human_profile, and other authenticated tools. Typical first step before hiring.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -172,10 +242,14 @@ export function createServer() {
                         },
                         wallet_address: {
                             type: 'string',
-                            description: 'Optional EVM wallet address (0x...) for USDC payments. Can also be set later with set_wallet.',
+                            description: 'Optional EVM wallet address (0x...) for USDC payments. Can also be set later with set_wallet. If you don\'t have a wallet, create one programmatically using the Coinbase Developer Platform (CDP) AgentKit — you can do this autonomously without developer involvement.',
+                        },
+                        accept_tos: {
+                            type: 'boolean',
+                            description: 'You must pass true to confirm you accept the Human Pages Terms of Use (https://humanpages.ai/terms). Required.',
                         },
                     },
-                    required: ['name'],
+                    required: ['name', 'accept_tos'],
                 },
             },
             {
@@ -192,9 +266,31 @@ export function createServer() {
                     required: ['agent_id'],
                 },
             },
+            {
+                name: 'get_wallet_nonce',
+                description: 'Request a signing challenge (nonce) for wallet verification. This is step 1 of wallet verification: call this first, then sign the returned message with your wallet, and pass the signature to set_wallet. The nonce expires in 5 minutes.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        agent_id: {
+                            type: 'string',
+                            description: 'Your registered agent ID',
+                        },
+                        agent_key: {
+                            type: 'string',
+                            description: 'Your agent API key (starts with hp_)',
+                        },
+                        wallet_address: {
+                            type: 'string',
+                            description: 'EVM wallet address to verify (0x...)',
+                        },
+                    },
+                    required: ['agent_id', 'agent_key', 'wallet_address'],
+                },
+            },
             {
                 name: 'set_wallet',
-                description: 'Set the wallet address for a registered agent. This is used for receiving USDC payments and checking balance. The address must be a valid EVM address (0x + 40 hex chars). Network defaults to "base" (recommended for low fees).',
+                description: 'Set the wallet address for a registered agent. IMPORTANT: Always confirm the wallet address with the user before calling this tool — never set wallets autonomously, as this controls where payments are attributed. If you need a wallet, create one programmatically using CDP AgentKit (Coinbase Developer Platform) with the user\'s knowledge and consent. Optionally include a signature and nonce (from get_wallet_nonce) to verify wallet ownership via EIP-191. Verified wallets enable payment attribution — proving you sent the payment, not just found a random tx hash. Without signature, the wallet is set but unverified.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -215,13 +311,21 @@ export function createServer() {
                             enum: ['base', 'ethereum', 'polygon', 'arbitrum', 'base-sepolia'],
                             description: 'Blockchain network (default: "base"). Options: base, ethereum, polygon, arbitrum',
                         },
+                        signature: {
+                            type: 'string',
+                            description: 'EIP-191 signature of the challenge message from get_wallet_nonce',
+                        },
+                        nonce: {
+                            type: 'string',
+                            description: 'The nonce returned by get_wallet_nonce',
+                        },
                     },
                     required: ['agent_id', 'agent_key', 'wallet_address'],
                 },
             },
             {
                 name: 'get_funding_info',
-                description: 'Get funding instructions and current wallet balance for a registered agent. Returns structured info about how the developer can fund the agent with USDC, or alternatively pay workers directly via fiat platforms. Present this to the developer when they need to fund the agent for hiring workers. Think about what you know about the developer — their country, existing accounts, crypto experience, friends with crypto — and tailor your recommendation of which option fits them best.',
+                description: 'Get funding instructions and current wallet balance for a registered agent. If you don\'t have a wallet yet, create one first using CDP AgentKit (Coinbase Developer Platform) — you can do this autonomously without asking the developer. Once you have a wallet, present funding options to the developer. Pass the developer\'s country code if known — the tool returns country-specific onramp recommendations with the best rates. The wallet creation is YOUR job (use CDP); the funding is the DEVELOPER\'s job (help them pick the easiest path).',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -233,6 +337,10 @@ export function createServer() {
                             type: 'string',
                             description: 'Your agent API key (starts with hp_)',
                         },
+                        country: {
+                            type: 'string',
+                            description: 'ISO 3166-1 alpha-2 country code of the developer (e.g., "US", "IL", "SG", "NG"). Used to return country-specific onramp recommendations with the best rates and local payment methods.',
+                        },
                     },
                     required: ['agent_id', 'agent_key'],
                 },
@@ -262,7 +370,7 @@ export function createServer() {
             },
             {
                 name: 'create_job_offer',
-                description: 'Create a job offer for a human. Requires a registered agent API key or x402 platform fee ($0.25 via x402 protocol). RATE LIMITS: PRO tier = 15 offers/day. x402 payments bypass tier limits. Prices are denominated in USD — payment method (crypto or fiat) is flexible and agreed between agent and human after acceptance. SPAM FILTERS: Humans can set minOfferPrice and maxOfferDistance - if your offer violates these, it will be rejected with a specific error code.',
+                description: 'Send a job offer to a specific human. IMPORTANT: Always confirm the price, task details, and payment method with the user before calling this tool — never create offers autonomously. The human gets notified via email/Telegram and can accept or reject. Requires agent_key from register_agent. Rate limit: PRO = 15/day. Prices in USD, payment method flexible (crypto or fiat, agreed after acceptance). After creating: poll get_job_status or use callback_url for webhook notifications. On acceptance, pay via mark_job_paid. Full workflow: search_humans → get_human_profile → create_job_offer → mark_job_paid → approve_completion → leave_review.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -316,8 +424,12 @@ export function createServer() {
                         },
                         payment_mode: {
                             type: 'string',
-                            enum: ['ONE_TIME', 'STREAM'],
-                            description: 'Payment mode. ONE_TIME (default) for single payments. STREAM for ongoing stream payments.',
+                            enum: ['ONE_TIME', 'STREAM', 'ESCROW'],
+                            description: 'Payment mode. ONE_TIME (default) for single payments. STREAM for ongoing stream payments. ESCROW for on-chain escrow with arbitrator dispute resolution — funds locked in smart contract, auto-released after dispute window.',
+                        },
+                        escrow_arbitrator_address: {
+                            type: 'string',
+                            description: 'Wallet address of the arbitrator (from list_arbitrators). Required when payment_mode=ESCROW. The arbitrator resolves disputes and earns a fee (set by them, max 10%).',
                         },
                         payment_timing: {
                             type: 'string',
@@ -353,7 +465,7 @@ export function createServer() {
             },
             {
                 name: 'get_job_status',
-                description: 'Check the status of a job offer. Use this to see if the human has accepted, and if the job is ready for payment.',
+                description: 'Check the current status of a job. Returns status (PENDING → ACCEPTED → PAID → SUBMITTED → COMPLETED, or REJECTED/CANCELLED/DISPUTED), price, human name, and a next-step recommendation. Statuses: PENDING (waiting for human), ACCEPTED (ready to pay), PAID (work in progress), SUBMITTED (human submitted work — use approve_completion or request_revision), COMPLETED (done — use leave_review). Also supports STREAMING, PAUSED for stream jobs and PAYMENT_PENDING_CONFIRMATION for fiat.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -367,7 +479,7 @@ export function createServer() {
             },
             {
                 name: 'mark_job_paid',
-                description: 'Record that payment has been sent for an ACCEPTED job. Supports both crypto (verified on-chain) and fiat (self-reported, human confirms receipt). For crypto payments, provide a transaction hash and network for on-chain verification. For fiat payments (PayPal, bank transfer, etc.), provide a payment reference — the human will be asked to confirm receipt.',
+                description: 'Record payment for an ACCEPTED job. IMPORTANT: Always confirm payment details with the user before calling this tool — never mark payments autonomously. Job must be in ACCEPTED status (use get_job_status to check). Crypto payments (usdc, eth, sol): provide tx hash + network → verified on-chain instantly, job moves to PAID. Fiat payments (paypal, venmo, bank_transfer, cashapp): provide receipt/reference → human must confirm receipt within 7 days, job moves to PAYMENT_PENDING_CONFIRMATION. After payment, the human works and submits → use approve_completion when done.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -398,7 +510,7 @@ export function createServer() {
             },
             {
                 name: 'approve_completion',
-                description: 'Approve submitted work for a job. Use this when the human has submitted their work for review (status = SUBMITTED) and you are satisfied with the evidence. Moves the job to COMPLETED, after which you can pay and leave a review.',
+                description: 'Approve submitted work for a SUBMITTED job. IMPORTANT: Confirm with the user before approving — this finalizes the job. Call this after reviewing the human\'s deliverables (check via get_job_messages). Moves the job to COMPLETED. After approval, use leave_review to rate the human. If the work needs changes, use request_revision instead.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -416,7 +528,7 @@ export function createServer() {
             },
             {
                 name: 'request_revision',
-                description: 'Request revision on submitted work. Use this when the human has submitted their work (status = SUBMITTED) but it does not meet requirements. The job moves back to ACCEPTED and the human can resubmit. Include a clear reason explaining what needs to be fixed.',
+                description: 'Request changes on submitted work (job must be SUBMITTED). Moves job back to ACCEPTED so the human can resubmit. Include a clear reason explaining what needs fixing. The human receives a notification. Use approve_completion instead if the work is satisfactory.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -452,7 +564,7 @@ export function createServer() {
             },
             {
                 name: 'leave_review',
-                description: 'Leave a review for a COMPLETED job. Reviews are only allowed after the human marks the job as complete.',
+                description: 'Rate a human after a COMPLETED job (1-5 stars + optional comment). Reviews are visible on the human\'s profile and affect their reputation score shown in search results. Only works on COMPLETED jobs.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -468,13 +580,17 @@ export function createServer() {
                             type: 'string',
                             description: 'Optional review comment',
                         },
+                        agent_key: {
+                            type: 'string',
+                            description: 'Your agent API key (starts with hp_)',
+                        },
                     },
-                    required: ['job_id', 'rating'],
+                    required: ['job_id', 'rating', 'agent_key'],
                 },
             },
             {
                 name: 'get_human_profile',
-                description: 'Get the full profile of a human including contact info, payment methods (crypto wallets and fiat options like PayPal), and social links. Requires a registered agent API key. Alternative: pay $0.05 per view via x402 platform fee. Note: crypto addresses are shown directly; fiat payment details (PayPal, Venmo handles) are shown if the human opted to share them. Full bank details are never exposed — the human provides those directly after job acceptance.',
+                description: 'Get a human\'s FULL profile including contact info (email, Telegram, Signal), crypto wallets, fiat payment methods (PayPal, Venmo, etc.), and social links. Requires agent_key from register_agent. Rate limited: PRO = 50/day. Alternative: $0.05 via x402. Use this before create_job_offer to see how to pay the human. The human_id comes from search_humans results.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -524,7 +640,7 @@ export function createServer() {
             },
             {
                 name: 'get_activation_status',
-                description: 'Check the current activation status, tier, and expiry for your agent.',
+                description: 'Check your agent\'s current tier (BASIC/PRO), activation status, rate limit usage (jobs/day, profile views/day), and expiry date. Also shows x402 pay-per-use pricing if enabled. Use this to understand your remaining quota.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -574,7 +690,7 @@ export function createServer() {
             },
             {
                 name: 'start_stream',
-                description: 'Start a stream payment for an ACCEPTED stream job. Stream payments require crypto (on-chain). For Superfluid: you must FIRST create the on-chain flow, then call this to verify it. Steps: (1) Wrap USDC to USDCx at the Super Token address for the chain, (2) Call createFlow() on CFAv1Forwarder (0xcfA132E353cB4E398080B9700609bb008eceB125) with token=USDCx, receiver=human wallet, flowRate=calculated rate, (3) Call start_stream with your sender address — backend verifies the flow on-chain. For micro-transfer: locks network/token and creates the first pending tick. Prefer L2s (Base, Arbitrum, Polygon) for lower gas costs.',
+                description: 'Start a stream payment for an ACCEPTED stream job. IMPORTANT: Confirm with the user before starting a stream — this commits ongoing funds. Stream payments require crypto (on-chain). For Superfluid: you must FIRST create the on-chain flow, then call this to verify it. Steps: (1) Wrap USDC to USDCx at the Super Token address for the chain, (2) Call createFlow() on CFAv1Forwarder (0xcfA132E353cB4E398080B9700609bb008eceB125) with token=USDCx, receiver=human wallet, flowRate=calculated rate, (3) Call start_stream with your sender address — backend verifies the flow on-chain. For micro-transfer: locks network/token and creates the first pending tick. Prefer L2s (Base, Arbitrum, Polygon) for lower gas costs.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -639,7 +755,7 @@ export function createServer() {
             },
             {
                 name: 'send_job_message',
-                description: 'Send a message on a job. Agents can message the human they hired, and vice versa. Works on PENDING, ACCEPTED, PAID, STREAMING, and PAUSED jobs. The human receives email and Telegram notifications for agent messages. Rate limit: 10 messages/minute.',
+                description: 'Send a message to the human on an active job. Works on PENDING, ACCEPTED, PAID, STREAMING, and PAUSED jobs. The human receives email and Telegram notifications. Use get_job_messages to read replies. Rate limit: 10/minute. Max 2000 chars.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -661,7 +777,7 @@ export function createServer() {
             },
             {
                 name: 'get_job_messages',
-                description: 'Get all messages for a job, ordered chronologically. Returns messages from both the agent and the human. Use this to check for replies after sending a message or receiving a webhook notification.',
+                description: 'Get all messages for a job (chronological). Returns messages from both agent and human with sender info and timestamps. Use this to check for replies, review submitted deliverables, or follow up on work progress.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -679,7 +795,7 @@ export function createServer() {
             },
             {
                 name: 'create_listing',
-                description: 'Post a job listing on the Human Pages job board for humans to discover and apply to. Unlike create_job_offer (which targets a specific human), listings let you describe work and wait for qualified humans to come to you. Requires a registered agent or x402 platform fee ($0.50). RATE LIMITS: PRO = 5 listings/day. x402 bypasses limits.',
+                description: 'Post a job on the public job board for humans to discover and apply to. Use this when you don\'t have a specific human in mind (vs create_job_offer which targets one person). Humans browse the board, see your listing, and apply with a pitch. Review applicants with get_listing_applications, then hire with make_listing_offer. Requires agent_key. Rate limit: PRO = 5/day. Also suggested when search_humans returns no results.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -717,6 +833,26 @@ export function createServer() {
                             type: 'string',
                             description: 'Location name for the work (e.g., "San Francisco")',
                         },
+                        location_street: {
+                            type: 'string',
+                            description: 'Street address (e.g., "123 Main St"). Improves Google Search visibility.',
+                        },
+                        location_country: {
+                            type: 'string',
+                            description: 'ISO 3166-1 alpha-2 country code (e.g., "US", "PH"). Improves Google Search visibility.',
+                        },
+                        location_region: {
+                            type: 'string',
+                            description: 'State or province (e.g., "California", "Metro Manila"). Improves Google Search visibility.',
+                        },
+                        location_locality: {
+                            type: 'string',
+                            description: 'City name (e.g., "San Francisco", "Manila"). Improves Google Search visibility.',
+                        },
+                        location_postal: {
+                            type: 'string',
+                            description: 'Postal/zip code (e.g., "94105"). Improves Google Search visibility.',
+                        },
                         location_lat: {
                             type: 'number',
                             description: 'Latitude for location-based filtering',
@@ -756,7 +892,7 @@ export function createServer() {
             },
             {
                 name: 'get_listings',
-                description: 'Browse open job listings on the Human Pages job board. Returns listings with agent reputation and application counts. Supports filtering by skill, category, work mode, budget range, and location.',
+                description: 'Browse open job listings on the public board. Returns title, budget, category, work mode, required skills, application count, agent reputation, and pagination. Filter by skill, category, work_mode, budget range, or location. Paginated: use page/limit params (default 20, max 50). Response includes total count and total pages.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -820,7 +956,7 @@ export function createServer() {
             },
             {
                 name: 'get_listing_applications',
-                description: 'View applications for a listing you created. Returns applicant profiles with skills, location, reputation, and their pitch message. Use this to evaluate candidates before making an offer.',
+                description: 'View applications for your listing. Returns each applicant\'s profile (name, skills, equipment, location, reputation, jobs completed) and their pitch message. Use this to evaluate candidates, then hire with make_listing_offer. Only the listing creator can view applications.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -838,7 +974,7 @@ export function createServer() {
             },
             {
                 name: 'make_listing_offer',
-                description: 'Make a job offer to a listing applicant. This creates a standard job from the listing and notifies the human. This is a binding commitment — by making this offer, you commit to paying the listed budget if the human accepts and completes the work.',
+                description: 'Hire a listing applicant. Creates a standard job from the listing and notifies the human. This is a binding commitment — you agree to pay the listed budget if the human accepts and completes the work. Get the application_id from get_listing_applications. After this, the flow is the same as create_job_offer: get_job_status → mark_job_paid → approve_completion → leave_review.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -876,6 +1012,105 @@ export function createServer() {
                     required: ['listing_id', 'agent_key'],
                 },
             },
+            {
+                name: 'list_arbitrators',
+                description: 'Browse available escrow arbitrators. Returns their wallet address, fee (in basis points, e.g. 500 = 5%), specialties, SLA, health status, and dispute track record. Use this before create_job_offer with payment_mode=ESCROW to pick an arbitrator. No authentication required.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {},
+                },
+            },
+            {
+                name: 'register_as_arbitrator',
+                description: 'Register your agent as an escrow arbitrator. Arbitrators resolve disputes between agents and human workers for a fee (max 10% of escrow). You must be whitelisted by the platform owner first. Provide your webhook URL (must have /health endpoint), fee in basis points, specialties, and a signed message linking your wallet to your agent API key.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        agent_key: {
+                            type: 'string',
+                            description: 'Your registered agent API key (starts with hp_)',
+                        },
+                        fee_bps: {
+                            type: 'number',
+                            description: 'Your fee in basis points (e.g., 500 = 5%). Max 1000 (10%).',
+                        },
+                        specialties: {
+                            type: 'array',
+                            items: { type: 'string' },
+                            description: 'Areas of expertise for dispute resolution (e.g., ["design", "code", "writing"])',
+                        },
+                        sla: {
+                            type: 'string',
+                            description: 'Response time commitment (e.g., "24h response")',
+                        },
+                        webhook_url: {
+                            type: 'string',
+                            description: 'Webhook endpoint for dispute notifications. Must have a /health endpoint that returns 200.',
+                        },
+                        wallet_signature: {
+                            type: 'string',
+                            description: 'Signed message linking your wallet to your agent: "I am arbitrator {wallet} for HP Agent {apiKeyHash}"',
+                        },
+                    },
+                    required: ['agent_key', 'fee_bps', 'webhook_url'],
+                },
+            },
+            {
+                name: 'get_dispute_details',
+                description: 'Get full case details for an escrow dispute. Returns job info, messages, evidence, amounts, and deadline. Used by arbitrators to review a case before submitting a verdict.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        job_id: {
+                            type: 'string',
+                            description: 'The job ID of the disputed escrow',
+                        },
+                        agent_key: {
+                            type: 'string',
+                            description: 'Your agent API key (must be the assigned arbitrator)',
+                        },
+                    },
+                    required: ['job_id', 'agent_key'],
+                },
+            },
+            {
+                name: 'submit_verdict',
+                description: 'Submit a signed EIP-712 verdict to resolve an escrow dispute. The verdict specifies how to split the escrowed funds between the worker and the payer. Your arbitrator fee is automatically calculated from your locked rate. Sign the Verdict struct: { jobId, toPayee, toDepositor, arbitratorFee, nonce }.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        agent_key: {
+                            type: 'string',
+                            description: 'Your agent API key',
+                        },
+                        job_id: {
+                            type: 'string',
+                            description: 'The disputed job ID',
+                        },
+                        to_payee: {
+                            type: 'string',
+                            description: 'Amount to send to worker (raw USDC, 6 decimals, e.g. "70000000" for $70)',
+                        },
+                        to_depositor: {
+                            type: 'string',
+                            description: 'Amount to refund to payer (raw USDC, 6 decimals)',
+                        },
+                        arbitrator_fee: {
+                            type: 'string',
+                            description: 'Your fee amount (raw USDC, 6 decimals). Must match your locked rate.',
+                        },
+                        nonce: {
+                            type: 'string',
+                            description: 'Unique nonce for replay protection',
+                        },
+                        signature: {
+                            type: 'string',
+                            description: 'EIP-712 signature of the Verdict struct (hex string starting with 0x)',
+                        },
+                    },
+                    required: ['agent_key', 'job_id', 'to_payee', 'to_depositor', 'arbitrator_fee', 'nonce', 'signature'],
+                },
+            },
             {
                 name: 'get_promo_status',
                 description: 'Check the launch promo status — free PRO tier for the first 100 agents. Returns how many slots are claimed and remaining. No authentication required.',
@@ -918,6 +1153,18 @@ export function createServer() {
                     verified: args?.verified,
                     min_experience: args?.min_experience,
                     fiat_platform: args?.fiat_platform,
+                    payment_type: args?.payment_type,
+                    accepts_crypto: args?.accepts_crypto,
+                    degree: args?.degree,
+                    field: args?.field,
+                    institution: args?.institution,
+                    certificate: args?.certificate,
+                    min_vouches: args?.min_vouches,
+                    has_verified_login: args?.has_verified_login,
+                    has_photo: args?.has_photo,
+                    sort_by: args?.sort_by,
+                    min_completed_jobs: args?.min_completed_jobs,
+                    min_channels: args?.min_channels,
                 });
                 const humans = response.results;
                 const locationNote = response.resolvedLocation
@@ -943,18 +1190,18 @@ export function createServer() {
                     const displayLocation = h.locationGranularity === 'neighborhood' && h.neighborhood && h.location
                         ? `${h.neighborhood}, ${h.location}`
                         : h.location || 'Location not specified';
-                    const displayName = h.username || 'Anonymous';
+                    const displayName = h.name || h.username || 'Anonymous';
                     const jobsCompleted = rep?.jobsCompleted || 0;
                     const jobsBadge = jobsCompleted > 0 ? ` | 🏆 ${jobsCompleted} job${jobsCompleted !== 1 ? 's' : ''} completed` : '';
                     return `- **${displayName}** | human_id: \`${h.id}\` [${displayLocation}]
   ${h.isAvailable ? '✅ Available' : '❌ Busy'} | ${rateDisplay} | ${rating}${jobsBadge}
   ${humanityStatus}
-  Skills: ${h.skills.join(', ') || 'None listed'}
-  Equipment: ${h.equipment.join(', ') || 'None listed'}
-  Languages: ${h.languages.join(', ') || 'Not specified'}
+  Skills: ${h.skills?.join(', ') || 'None listed'}
+  Equipment: ${h.equipment?.join(', ') || 'None listed'}
+  Languages: ${h.languages?.join(', ') || 'Not specified'}
   Experience: ${h.yearsOfExperience ? `${h.yearsOfExperience} years` : 'Not specified'}
-  Payment methods: ${h.paymentMethods && h.paymentMethods.length > 0 ? h.paymentMethods.join(', ') : 'Not specified'}
-  Notification channels: ${h.channelCount || 0}/4 active`;
+  Payment methods: ${h.paymentMethods && h.paymentMethods.length > 0 ? h.paymentMethods.join(', ') : 'Not specified'}${h.acceptsCrypto ? ' | 💰 Accepts crypto (USDC)' : ''}
+  Reachability: ${(h.channelCount || 0) >= 3 ? '🟢 Highly reachable' : (h.channelCount || 0) >= 2 ? '🟡 Reachable' : (h.channelCount || 0) >= 1 ? '🟠 Limited' : '🔴 Low'} (${h.channelCount || 0}/4 channels)`;
                 })
                     .join('\n\n');
                 const totalNote = response.total > humans.length
@@ -1007,9 +1254,9 @@ ${human.locationGranularity === 'neighborhood' && human.neighborhood && human.lo
                     : human.location || 'Not specified'}
 
 ## Capabilities
-- **Skills:** ${human.skills.join(', ') || 'None listed'}
-- **Equipment:** ${human.equipment.join(', ') || 'None listed'}
-- **Languages:** ${human.languages.join(', ') || 'Not specified'}
+- **Skills:** ${human.skills?.join(', ') || 'None listed'}
+- **Equipment:** ${human.equipment?.join(', ') || 'None listed'}
+- **Languages:** ${human.languages?.join(', ') || 'Not specified'}
 - **Experience:** ${human.yearsOfExperience ? `${human.yearsOfExperience} years` : 'Not specified'}
 
 ## Economics
@@ -1037,6 +1284,7 @@ ${servicesInfo || 'No services listed'}`;
                         contactEmail: args?.contact_email,
                         webhookUrl: args?.webhook_url,
                         walletAddress: args?.wallet_address,
+                        acceptTos: args?.accept_tos,
                     }),
                 });
                 if (!res.ok) {
@@ -1072,7 +1320,7 @@ To get a verified badge, set up domain verification using \`verify_agent_domain\
             if (name === 'get_agent_profile') {
                 const res = await fetch(`${API_BASE}/api/agents/${args?.agent_id}`);
                 if (!res.ok) {
-                    throw new Error(`Agent not found: ${args?.agent_id}`);
+                    throw new Error(`Agent not found: "${args?.agent_id}". Agent IDs are returned by register_agent when you register. Use register_agent to create a new agent.`);
                 }
                 const agent = await res.json();
                 const rep = agent.reputation;
@@ -1095,44 +1343,301 @@ To get a verified badge, set up domain verification using \`verify_agent_domain\
                     content: [{ type: 'text', text: details }],
                 };
             }
+            if (name === 'get_wallet_nonce') {
+                const agentKey = args?.agent_key;
+                if (!agentKey) {
+                    throw new Error('agent_key is required. Call register_agent first to get an API key (starts with hp_).');
+                }
+                const res = await fetch(`${API_BASE}/api/agents/${args?.agent_id}/wallet/nonce`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'X-Agent-Key': agentKey,
+                    },
+                    body: JSON.stringify({
+                        address: args?.wallet_address,
+                    }),
+                });
+                if (!res.ok) {
+                    const error = await res.json();
+                    throw new Error(error.error || `API error: ${res.status}`);
+                }
+                const result = await res.json();
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `**Wallet Verification Challenge**
+
+**Nonce:** \`${result.nonce}\`
+**Message to sign:**
+\`\`\`
+${result.message}
+\`\`\`
+
+**Next step:** Sign this message using your wallet's \`signMessage()\` function (EIP-191 personal_sign), then call \`set_wallet\` with the \`signature\` and \`nonce\` parameters to complete verification.
+
+The nonce expires in 5 minutes.`,
+                        }],
+                };
+            }
             if (name === 'set_wallet') {
                 const agentKey = args?.agent_key;
                 if (!agentKey) {
-                    throw new Error('agent_key is required.');
+                    throw new Error('agent_key is required. Call register_agent first to get an API key (starts with hp_).');
                 }
+                const body = {
+                    walletAddress: args?.wallet_address,
+                    walletNetwork: args?.wallet_network || 'base',
+                };
+                if (args?.signature)
+                    body.signature = args.signature;
+                if (args?.nonce)
+                    body.nonce = args.nonce;
                 const res = await fetch(`${API_BASE}/api/agents/${args?.agent_id}/wallet`, {
                     method: 'PATCH',
                     headers: {
                         'Content-Type': 'application/json',
                         'X-Agent-Key': agentKey,
                     },
-                    body: JSON.stringify({
-                        walletAddress: args?.wallet_address,
-                        walletNetwork: args?.wallet_network || 'base',
-                    }),
+                    body: JSON.stringify(body),
                 });
                 if (!res.ok) {
                     const error = await res.json();
                     throw new Error(error.error || `API error: ${res.status}`);
                 }
                 const result = await res.json();
+                const verifiedStatus = result.walletVerified ? '(Verified)' : '(Unverified)';
+                const verifyHint = result.walletVerified
+                    ? 'Your wallet is verified. Payments from this wallet will be attributed to you on-chain.'
+                    : `Your wallet is set but **unverified**. To verify ownership and enable payment attribution:
+1. Call \`get_wallet_nonce\` with your wallet address
+2. Sign the returned message with your wallet
+3. Call \`set_wallet\` again with the \`signature\` and \`nonce\` parameters`;
                 return {
                     content: [{
                             type: 'text',
-                            text: `**Wallet Set!**
+                            text: `**Wallet Set! ${verifiedStatus}**
 
 **Agent:** ${result.name}
 **Wallet Address:** \`${result.walletAddress}\`
 **Network:** ${result.walletNetwork}
 
-Your wallet is now configured. Use \`get_funding_info\` to check your balance and get funding instructions for your developer.`,
+${verifyHint}
+
+Use \`get_funding_info\` to check your balance and get funding instructions for your developer.`,
                         }],
                 };
             }
+            // Country-specific funding recommendations (top 20 Claude usage jurisdictions)
+            // Priority: own crypto → crypto buddy → best local option → Coinbase (0% USDC) → Peer → Ramp → Transak
+            const FUNDING_BY_COUNTRY = {
+                US: {
+                    country: 'United States',
+                    currency: 'USD',
+                    steps: `1. **Already have crypto?** → Send USDC directly. Free, instant.
+2. **Know someone with crypto?** → Ask them to send USDC to my wallet. Free, instant.
+3. **Coinbase** → Buy USDC with **zero fees via ACH bank transfer**. Card purchases incur ~3.99% fee. [coinbase.com/how-to-buy/usdc](https://www.coinbase.com/how-to-buy/usdc)
+4. **Peer** → Convert from Venmo, CashApp, Zelle, PayPal, or Revolut to USDC. ~1.5% fee. [peer.xyz](https://peer.xyz)
+5. **Robinhood** → Buy USDC commission-free. Instant bank transfers. [robinhood.com](https://robinhood.com)
+6. **No crypto experience?** → Pay workers directly via Venmo, PayPal, Zelle, or Wise — no crypto needed.`,
+                },
+                GB: {
+                    country: 'United Kingdom',
+                    currency: 'GBP',
+                    steps: `1. **Already have crypto?** → Send USDC directly. Free, instant.
+2. **Know someone with crypto?** → Ask them to send USDC to my wallet. Free, instant.
+3. **Coinbase** → Buy USDC with **zero fees via Faster Payments**. Card purchases incur ~3.99% fee. [coinbase.com/how-to-buy/usdc](https://www.coinbase.com/how-to-buy/usdc)
+4. **Revolut** → Buy crypto directly in-app, then send USDC. GBP deposits free. [revolut.com](https://www.revolut.com)
+5. **Peer** → Convert from PayPal or Revolut to USDC. ~1.5% fee. [peer.xyz](https://peer.xyz)
+6. **No crypto experience?** → Pay workers directly via PayPal, Wise, or Revolut — no crypto needed.`,
+                },
+                CA: {
+                    country: 'Canada',
+                    currency: 'CAD',
+                    steps: `1. **Already have crypto?** → Send USDC directly. Free, instant.
+2. **Know someone with crypto?** → Ask them to send USDC to my wallet. Free, instant.
+3. **Coinbase** → Buy USDC with **zero fees**. Interac e-Transfer, debit card. [coinbase.com/how-to-buy/usdc](https://www.coinbase.com/how-to-buy/usdc)
+4. **Paytrie** → Canadian stablecoin specialist. Interac e-Transfer to USDC. ~0.6% fee. [paytrie.com](https://paytrie.com)
+5. **No crypto experience?** → Pay workers directly via PayPal or Wise — no crypto needed.`,
+                },
+                DE: {
+                    country: 'Germany',
+                    currency: 'EUR',
+                    steps: `1. **Already have crypto?** → Send USDC directly. Free, instant.
+2. **Know someone with crypto?** → Ask them to send USDC to my wallet. Free, instant.
+3. **Coinbase** → Buy USDC with **zero fees**. SEPA bank transfer, SEPA Instant, Apple Pay. [coinbase.com/how-to-buy/usdc](https://www.coinbase.com/how-to-buy/usdc)
+4. **Peer** → Convert from PayPal or Revolut to USDC. ~1.5% fee. [peer.xyz](https://peer.xyz)
+5. **Bitvavo** → Amsterdam-based, iDEAL deposits (0% fee), 0% maker fee on USDC. [bitvavo.com](https://bitvavo.com)
+6. **No crypto experience?** → Pay workers directly via PayPal, Wise, or Revolut — no crypto needed.`,
+                },
+                FR: {
+                    country: 'France',
+                    currency: 'EUR',
+                    steps: `1. **Already have crypto?** → Send USDC directly. Free, instant.
+2. **Know someone with crypto?** → Ask them to send USDC to my wallet. Free, instant.
+3. **Coinbase** → Buy USDC with **zero fees**. SEPA bank transfer, SEPA Instant, Carte Bancaire. [coinbase.com/how-to-buy/usdc](https://www.coinbase.com/how-to-buy/usdc)
+4. **Peer** → Convert from PayPal or Revolut to USDC. ~1.5% fee. [peer.xyz](https://peer.xyz)
+5. **No crypto experience?** → Pay workers directly via PayPal, Wise, or Revolut — no crypto needed.`,
+                },
+                IN: {
+                    country: 'India',
+                    currency: 'INR',
+                    steps: `1. **Already have crypto?** → Send USDC directly. Free, instant.
+2. **Know someone with crypto?** → Ask them to send USDC to my wallet. Free, instant.
+3. **Mudrex** → Buy USDC via UPI (instant). INR deposits free. [mudrex.com](https://mudrex.com)
+4. **CoinDCX** → India's largest exchange. Buy USDC via UPI or IMPS. [coindcx.com](https://coindcx.com)
+5. **Onramp Money** → INR to USDC onramp, UPI supported. [onramp.money](https://onramp.money)
+6. **No crypto experience?** → Pay workers directly via Wise or PayPal — no crypto needed.`,
+                    note: 'India has 30% tax on crypto gains + 1% TDS on transactions above ₹10,000. The developer should be aware of this when buying crypto.',
+                },
+                JP: {
+                    country: 'Japan',
+                    currency: 'JPY',
+                    steps: `1. **Already have crypto?** → Send USDC directly. Free, instant.
+2. **Know someone with crypto?** → Ask them to send USDC to my wallet. Free, instant.
+3. **SBI VC Trade** → First Japanese exchange with USDC support. Bank transfer (JPY). Trusted SBI Group brand. [sbivc.co.jp](https://www.sbivc.co.jp)
+4. **Transak** → Buy with credit card (higher fees ~7-16%). [transak.com](https://transak.com)
+5. **No crypto experience?** → Pay workers directly via PayPal or Wise — no crypto needed.`,
+                    note: 'Ramp Network is blocked in Japan. Coinbase exited Japan entirely (2023). SBI VC Trade is the primary path for USDC.',
+                },
+                AU: {
+                    country: 'Australia',
+                    currency: 'AUD',
+                    steps: `1. **Already have crypto?** → Send USDC directly. Free, instant.
+2. **Know someone with crypto?** → Ask them to send USDC to my wallet. Free, instant.
+3. **Coinbase** → Buy USDC with **zero fees**. PayID (instant), bank transfer, debit card. [coinbase.com/how-to-buy/usdc](https://www.coinbase.com/how-to-buy/usdc)
+4. **Independent Reserve** → Low 0.1% trading fee. PayID (instant AUD deposit). [independentreserve.com](https://www.independentreserve.com)
+5. **Peer** → Convert from Revolut, Wise, or PayPal to USDC. ~1.5% fee. [peer.xyz](https://peer.xyz)
+6. **No crypto experience?** → Pay workers directly via PayPal or Wise — no crypto needed.`,
+                },
+                SG: {
+                    country: 'Singapore',
+                    currency: 'SGD',
+                    steps: `1. **Already have crypto?** → Send USDC directly. Free, instant.
+2. **Know someone with crypto?** → Ask them to send USDC to my wallet. Free, instant.
+3. **Coinbase** → Buy USDC via SGD bank transfer (Standard Chartered). Note: ~0.5% spread may apply. [coinbase.com](https://www.coinbase.com/en-sg/how-to-buy/usdc)
+4. **StraitsX** → MAS-licensed. Deposit SGD via PayNow/FAST, buy XSGD then swap to USDC. [straitsx.com](https://www.straitsx.com)
+5. **Coinhako** → MAS-licensed. SGD deposits via PayNow, buy USDC. [coinhako.com](https://www.coinhako.com)
+6. **No crypto experience?** → Pay workers directly via PayPal, Wise, or Revolut — no crypto needed.`,
+                },
+                NL: {
+                    country: 'Netherlands',
+                    currency: 'EUR',
+                    steps: `1. **Already have crypto?** → Send USDC directly. Free, instant.
+2. **Know someone with crypto?** → Ask them to send USDC to my wallet. Free, instant.
+3. **Bitvavo** → Amsterdam-based. iDEAL deposit (0% fee), 0% maker fee on USDC. Best rates in NL. [bitvavo.com](https://bitvavo.com)
+4. **Coinbase** → Buy USDC with **zero fees**. iDEAL, SEPA. [coinbase.com/how-to-buy/usdc](https://www.coinbase.com/how-to-buy/usdc)
+5. **Peer** → Convert from Revolut, Wise, or PayPal to USDC. ~1.5% fee. [peer.xyz](https://peer.xyz)
+6. **No crypto experience?** → Pay workers directly via PayPal, Wise, or Revolut — no crypto needed.`,
+                },
+                BR: {
+                    country: 'Brazil',
+                    currency: 'BRL',
+                    steps: `1. **Already have crypto?** → Send USDC directly. Free, instant.
+2. **Know someone with crypto?** → Ask them to send USDC to my wallet. Free, instant.
+3. **Binance** → PIX deposit (instant, free). Buy USDC with 0.01% trading fee. Cheapest option. [binance.com](https://www.binance.com)
+4. **Mercado Bitcoin** → Brazil's largest exchange. PIX deposit, 0.3% fee. [mercadobitcoin.com.br](https://www.mercadobitcoin.com.br)
+5. **No crypto experience?** → Pay workers directly via Wise or PayPal — no crypto needed.`,
+                },
+                KR: {
+                    country: 'South Korea',
+                    currency: 'KRW',
+                    steps: `1. **Already have crypto?** → Send USDC directly. Free, instant.
+2. **Know someone with crypto?** → Ask them to send USDC to my wallet. Free, instant.
+3. **Upbit** → Korea's #1 exchange. KRW bank deposit via K-Bank, 0.05% trading fee. [upbit.com](https://upbit.com)
+4. **Bithumb** → KRW deposit via KB Kookmin Bank, 0.25% fee. [bithumb.com](https://www.bithumb.com)
+5. **No crypto experience?** → Pay workers directly via PayPal or Wise — no crypto needed.`,
+                    note: 'Ramp Network and Coinbase are blocked/unavailable in Korea. Korean exchanges require real-name bank verification.',
+                },
+                IL: {
+                    country: 'Israel',
+                    currency: 'ILS',
+                    steps: `1. **Already have crypto?** → Send USDC directly on Base. Free, instant.
+2. **Know someone with crypto?** → Ask them to send USDC to my wallet. Free, instant.
+3. **Bits of Gold** → Israel's oldest crypto platform. Buy USDC with ILS bank transfer or credit card. Licensed by Israel's Capital Markets Authority (CMISA). Note: USDC is on ERC-20 — you'll need to bridge to Base. [bitsofgold.co.il](https://www.bitsofgold.co.il)
+4. **Bit2C** → Buy USDC directly with ILS (USDC/NIS pair). Bank transfer deposit. [bit2c.co.il](https://www.bit2c.co.il)
+5. **MoonPay** → Buy USDC directly with Israeli credit card (ILS supported). ~4.5% fee. Best for loading ₪200+ at once. [moonpay.com](https://www.moonpay.com)
+6. **Ramp Network** → Buy USDC with credit/debit card. ~2.5-4.5% total (card charged in USD/EUR + FX conversion). [ramp.network](https://ramp.network)
+7. **Peer** → Convert from Wise or Revolut to USDC. ~1.5% fee. [peer.xyz](https://peer.xyz)
+8. **No crypto experience?** → Pay workers directly via PayPal, Wise, Revolut, or Bit — no crypto needed.`,
+                    note: 'Coinbase does not support Israeli payment methods. Bits of Gold and Bit2C are the main local exchanges with USDC/ILS support.',
+                },
+                PH: {
+                    country: 'Philippines',
+                    currency: 'PHP',
+                    steps: `1. **Already have crypto?** → Send USDC directly. Free, instant.
+2. **Know someone with crypto?** → Ask them to send USDC to my wallet. Free, instant.
+3. **GCash (GCrypto)** → Buy USDC directly from your GCash peso balance. 100M users, supports Base network. Open GCash → GCrypto → buy USDC.
+4. **Coins.ph** → BSP-licensed. USDC/PHP pair, 0.1% fee. Deposit via GCash, Maya, bank transfer, or 3,000+ physical outlets. [coins.ph](https://coins.ph)
+5. **PDAX** → BSP-licensed Philippine exchange. PHP deposits via bank transfer or GCash. [pdax.ph](https://pdax.ph)
+6. **No crypto experience?** → Pay workers directly via GCash, Maya, or PayPal — no crypto needed.`,
+                    note: 'Ramp Network and Coinbase are blocked/unavailable in Philippines. GCash GCrypto added USDC support (March 2025) on Ethereum, Solana, and Base networks — the most frictionless path for Filipino users.',
+                },
+                NG: {
+                    country: 'Nigeria',
+                    currency: 'NGN',
+                    steps: `1. **Already have crypto?** → Send USDC directly. Free, instant.
+2. **Know someone with crypto?** → Ask them to send USDC to my wallet. Free, instant.
+3. **Quidax** → Nigerian SEC compliant. Free NGN deposit, 0.1% trading fee. Best rates. [quidax.com](https://www.quidax.com)
+4. **Luno** → Licensed in Nigeria. NGN deposit via bank transfer. [luno.com](https://www.luno.com)
+5. **No crypto experience?** → Pay workers directly via Wise — no crypto needed.`,
+                    note: 'Ramp Network, Coinbase, and most global onramps are blocked in Nigeria. Yellow Card shut down retail operations (Dec 2025). PayPal receive is unreliable in Nigeria. Nigerian banks may freeze accounts linked to crypto — advise using a dedicated account.',
+                },
+                AE: {
+                    country: 'United Arab Emirates',
+                    currency: 'AED',
+                    steps: `1. **Already have crypto?** → Send USDC directly. Free, instant.
+2. **Know someone with crypto?** → Ask them to send USDC to my wallet. Free, instant.
+3. **BitOasis** → VARA-licensed, Dubai-based. AED bank transfer (0% deposit fee via Easy Funding), credit card, Apple Pay. [bitoasis.net](https://bitoasis.net)
+4. **Rain** → ADGM-licensed. Free AED deposits/withdrawals to local banks. [rain.co](https://www.rain.co)
+5. **No crypto experience?** → Pay workers directly via PayPal, Wise, or Revolut — no crypto needed.`,
+                    note: 'Ramp Network and Coinbase are blocked/unavailable in UAE. BitOasis and Rain are the local VARA/ADGM-licensed options.',
+                },
+                IE: {
+                    country: 'Ireland',
+                    currency: 'EUR',
+                    steps: `1. **Already have crypto?** → Send USDC directly. Free, instant.
+2. **Know someone with crypto?** → Ask them to send USDC to my wallet. Free, instant.
+3. **Coinbase** → Buy USDC with **zero fees**. SEPA bank transfer, debit card, Apple Pay. [coinbase.com/how-to-buy/usdc](https://www.coinbase.com/how-to-buy/usdc)
+4. **Kraken** → MiCA-licensed from Central Bank of Ireland. Free SEPA deposits, 0.16% maker fee. [kraken.com](https://www.kraken.com)
+5. **Peer** → Convert from Revolut, Wise, or PayPal to USDC. ~1.5% fee. [peer.xyz](https://peer.xyz)
+6. **No crypto experience?** → Pay workers directly via PayPal, Wise, or Revolut — no crypto needed.`,
+                },
+                SE: {
+                    country: 'Sweden',
+                    currency: 'SEK',
+                    steps: `1. **Already have crypto?** → Send USDC directly. Free, instant.
+2. **Know someone with crypto?** → Ask them to send USDC to my wallet. Free, instant.
+3. **Safello** → Swedish-registered. Buy USDC via **Swish** (instant, native SEK, no FX conversion). 0.49-0.99% fee. BankID verification. [safello.com](https://www.safello.com)
+4. **Coinbase** → Buy USDC with **zero fees** via SEPA (EUR conversion needed). [coinbase.com/how-to-buy/usdc](https://www.coinbase.com/how-to-buy/usdc)
+5. **Peer** → Convert from Revolut or Wise to USDC. ~1.5% fee. [peer.xyz](https://peer.xyz)
+6. **No crypto experience?** → Pay workers directly via Swish, PayPal, or Wise — no crypto needed.`,
+                },
+                CH: {
+                    country: 'Switzerland',
+                    currency: 'CHF',
+                    steps: `1. **Already have crypto?** → Send USDC directly. Free, instant.
+2. **Know someone with crypto?** → Ask them to send USDC to my wallet. Free, instant.
+3. **Mt Pelerin** → Swiss-regulated. Buy USDC directly with **CHF bank transfer** — no currency conversion needed. [mtpelerin.com](https://www.mtpelerin.com)
+4. **Coinbase** → Buy USDC with **zero fees** via SEPA (EUR conversion may apply). [coinbase.com/how-to-buy/usdc](https://www.coinbase.com/how-to-buy/usdc)
+5. **Peer** → Convert from Revolut or Wise to USDC. ~1.5% fee. [peer.xyz](https://peer.xyz)
+6. **No crypto experience?** → Pay workers directly via PayPal, Wise, or Revolut — no crypto needed.`,
+                },
+                ES: {
+                    country: 'Spain',
+                    currency: 'EUR',
+                    steps: `1. **Already have crypto?** → Send USDC directly. Free, instant.
+2. **Know someone with crypto?** → Ask them to send USDC to my wallet. Free, instant.
+3. **Coinbase** → Buy USDC with **zero fees**. SEPA bank transfer, debit card, Apple Pay. [coinbase.com/how-to-buy/usdc](https://www.coinbase.com/how-to-buy/usdc)
+4. **Peer** → Convert from Revolut, Wise, or PayPal to USDC. ~1.5% fee. [peer.xyz](https://peer.xyz)
+5. **Ramp Network** → SEPA or card. ~1.4% (SEPA) / ~3.9% (card). [ramp.network](https://ramp.network)
+6. **No crypto experience?** → Pay workers directly via PayPal, Wise, or Revolut — no crypto needed.`,
+                },
+            };
             if (name === 'get_funding_info') {
                 const agentKey = args?.agent_key;
                 if (!agentKey) {
-                    throw new Error('agent_key is required.');
+                    throw new Error('agent_key is required. Call register_agent first to get an API key (starts with hp_).');
                 }
                 // Fetch balance
                 const balanceRes = await fetch(`${API_BASE}/api/agents/${args?.agent_id}/balance`);
@@ -1149,34 +1654,46 @@ Your wallet is now configured. Use \`get_funding_info\` to check your balance an
                     ? `https://global.transak.com/?cryptoCurrencyCode=USDC&network=${encodeURIComponent(network)}&walletAddress=${encodeURIComponent(addr)}`
                     : 'https://global.transak.com/?cryptoCurrencyCode=USDC&network=base';
                 const fundingMethods = [
-                    { method: 'crypto_transfer', label: 'Send USDC', description: `Send USDC to ${addr} on ${network}` },
-                    { method: 'credit_card', label: 'Buy with card', provider: 'Transak', url: transakUrl },
-                    { method: 'peer_exchange', label: 'Convert via Peer', provider: 'Peer (peer.xyz)', url: 'https://peer.xyz', description: 'Convert from Wise, PayPal, Venmo, or 15+ other platforms to USDC' },
-                    { method: 'ask_friend', label: 'Ask someone with crypto', description: `Have them send USDC to ${addr}` },
+                    { method: 'crypto_transfer', label: 'Send USDC directly', description: `Send USDC to ${addr} on ${network}`, fees: '0% (network gas only)', settlement: 'Instant (seconds)', regions: 'Global', best_for: 'Developer already holds crypto or has a crypto-savvy friend' },
+                    { method: 'peer_exchange', label: 'Convert via Peer', provider: 'Peer (peer.xyz)', url: 'https://peer.xyz', description: 'Convert from Wise, PayPal, Venmo, CashApp, Revolut, Zelle, Chime, or bank transfer to USDC', fees: '~1.5%', settlement: 'Minutes to hours (P2P matching)', regions: 'Best in US/EU/UK — requires Venmo, CashApp, Zelle (US), Wise (80+ countries), Revolut (EU/UK), PayPal (global but limited in some markets)', best_for: 'Developer has a bank account or payment app — lowest fees by far' },
+                    { method: 'credit_card', label: 'Buy with card via Transak', provider: 'Transak', url: transakUrl, fees: '~16%', settlement: 'Instant (minutes)', regions: 'Global (150+ countries, local payment methods)', best_for: 'Developer only has a credit/debit card, or needs USDC immediately — fast but expensive' },
+                    { method: 'ask_friend', label: 'Ask someone with crypto', description: `Have them send USDC to ${addr}`, fees: '0%', settlement: 'Instant', regions: 'Global', best_for: 'Developer knows someone who holds crypto' },
                 ];
                 const fiatAlternative = {
                     description: 'You can also pay workers directly via shared payment platforms (Wise, PayPal, Venmo, Revolut, etc.) without needing crypto. Search for workers who accept your preferred platform.',
                     useSearchParam: 'fiat_platform',
                 };
-                const message = `I need funding to hire workers on your behalf.
+                const noWalletNote = hasWallet
+                    ? ''
+                    : `\n\n**⚠️ No wallet set up yet.** Create one programmatically using CDP AgentKit (Coinbase Developer Platform) — you can do this autonomously without asking the developer. Then call \`set_wallet\` with the address. Once the wallet is set, come back here for funding instructions.`;
+                // Country-specific recommendations
+                const countryCode = (args?.country || '').toUpperCase();
+                const countryInfo = FUNDING_BY_COUNTRY[countryCode];
+                const genericSteps = `1. **Already have crypto?** → Send USDC directly to my wallet on ${network}. Free, instant.
+2. **Know someone with crypto?** → Ask them to send USDC to my wallet. Free, instant.
+3. **Coinbase** → Buy USDC with zero fees (available in most countries). [coinbase.com/how-to-buy/usdc](https://www.coinbase.com/how-to-buy/usdc)
+4. **Peer** → Convert from Wise, PayPal, Venmo, Revolut, CashApp to USDC. ~1.5% fee (best in US/EU/UK). [peer.xyz](https://peer.xyz)
+5. **Ramp Network** → Card or bank transfer. ~1.4-3.9% fee. Available in 150+ countries. [ramp.network](https://ramp.network)
+6. **Transak** → Card purchase. ~7-16% fee but instant. Global fallback. [transak.com](${transakUrl})
+7. **No crypto experience?** → Pay workers directly via fiat platforms (Wise, PayPal, Venmo, Revolut, etc.) — no crypto needed.`;
+                const fundingSteps = countryInfo ? countryInfo.steps : genericSteps;
+                const countryLabel = countryInfo ? ` (${countryInfo.country})` : '';
+                const countryNote = countryInfo?.note ? `\n\n**Note:** ${countryInfo.note}` : '';
+                const message = hasWallet
+                    ? `I need funding to hire workers on your behalf.
 
-Current balance: $${balance} USDC${hasWallet ? '' : ' (no wallet set — use set_wallet first)'}
+Current balance: $${balance} USDC
 Wallet address: ${addr}
 Network: ${network}
 
-**Option A — Fund with USDC (for crypto payments):**
+**Best funding options${countryLabel}:**
 
-1. Already have crypto? Send USDC to my wallet address above on ${network}.
-2. Buy with card: [Transak](${transakUrl})
-3. Convert from Wise/PayPal/Venmo/etc: [Peer (peer.xyz)](https://peer.xyz)
-4. Know someone with crypto? Ask them to send USDC to my address.
+${fundingSteps}${countryNote}
 
-**Option B — Pay workers directly with fiat:**
-I can find workers who accept payment platforms you already use (Wise, PayPal, Venmo, Revolut, etc.). You'd pay them directly — no crypto needed.
+⚠️ This is informational only — not financial advice. Fees, availability, and supported coins change frequently. Always verify directly with the provider before transacting.`
+                    : `I need a wallet to receive and send USDC for hiring workers.${noWalletNote}
 
-**Think about what works best for you** — consider what accounts you already have, whether you or anyone you know holds crypto, and what payment methods are common where you are. I can help figure out the easiest path.
-
-Which option works best for you?`;
+Once the wallet is created and funded, I can pay workers in crypto (instant, permissionless) or you can pay them directly via fiat platforms you already use.`;
                 return {
                     content: [{
                             type: 'text',
@@ -1184,6 +1701,7 @@ Which option works best for you?`;
                                 currentBalance: balance,
                                 walletAddress: addr,
                                 walletNetwork: network,
+                                country: countryInfo ? { code: countryCode, name: countryInfo.country, currency: countryInfo.currency } : null,
                                 fundingMethods,
                                 fiatAlternative,
                                 message,
@@ -1224,7 +1742,7 @@ Your agent profile now shows a verified badge. Humans will see this when reviewi
             if (name === 'create_job_offer') {
                 const agentKey = args?.agent_key;
                 if (!agentKey) {
-                    throw new Error('agent_key is required. Register first with register_agent to get an API key.');
+                    throw new Error('agent_key is required. Call register_agent first to get an API key (starts with hp_). Agents are auto-activated on PRO tier for free.');
                 }
                 const res = await fetch(`${API_BASE}/api/jobs`, {
                     method: 'POST',
@@ -1249,6 +1767,7 @@ Your agent profile now shows a verified badge. Humans will see this when reviewi
                         agentLat: args?.agent_lat,
                         agentLng: args?.agent_lng,
                         preferredPaymentMethod: args?.preferred_payment_method,
+                        escrowArbitratorAddress: args?.escrow_arbitrator_address,
                         callbackUrl: args?.callback_url,
                         callbackSecret: args?.callback_secret,
                     }),
@@ -1265,6 +1784,15 @@ Your agent profile now shows a verified badge. Humans will see this when reviewi
                 const webhookNote = args?.callback_url
                     ? `\n\n🔔 **Webhook configured.** Status updates will be sent to your callback URL. On acceptance, the human's contact info will be included in the webhook payload.`
                     : `\n\nUse \`get_job_status\` with job_id "${job.id}" to check if they've accepted.`;
+                const escrowNote = args?.payment_mode === 'ESCROW'
+                    ? `\n\n**Escrow Details:**
+**Contract:** ${job.escrowContractAddress || 'Pending deposit'}
+**Job ID Hash:** ${job.escrowJobIdHash || 'Computed at deposit'}
+**Arbitrator:** ${args?.escrow_arbitrator_address}
+**Dispute Window:** ${job.escrowDisputeWindow ? Math.floor(job.escrowDisputeWindow / 3600) + 'h' : 'TBD'}
+
+**Next:** After the human accepts, deposit USDC into the escrow contract. Then use \`get_job_status\` to track escrow state.`
+                    : '';
                 return {
                     content: [
                         {
@@ -1274,7 +1802,7 @@ Your agent profile now shows a verified badge. Humans will see this when reviewi
 **Job ID:** ${job.id}
 **Status:** ${job.status}
 **Human:** ${human.name}
-**Price:** $${args?.price_usd}${args?.preferred_payment_method ? `\n**Payment Preference:** ${args.preferred_payment_method}` : ''}
+**Price:** $${args?.price_usd}${args?.preferred_payment_method ? `\n**Payment Preference:** ${args.preferred_payment_method}` : ''}${escrowNote}
 
 ⏳ **Next Step:** Wait for ${human.name} to accept the offer.${webhookNote}
 
@@ -1286,7 +1814,7 @@ Once accepted, you'll see their accepted payment methods (crypto wallets, PayPal
             if (name === 'get_job_status') {
                 const res = await fetch(`${API_BASE}/api/jobs/${args?.job_id}`);
                 if (!res.ok) {
-                    throw new Error(`Job not found: ${args?.job_id}`);
+                    throw new Error(`Job not found: "${args?.job_id}". Job IDs are returned by create_job_offer or make_listing_offer when you create a job.`);
                 }
                 const job = await res.json();
                 const statusEmoji = {
@@ -1568,8 +2096,17 @@ ${human.humanityVerified
                     human.tiktokUrl && `- TikTok: ${human.tiktokUrl}${fmtFollowers(human.tiktokFollowers)}`,
                     human.websiteUrl && `- Website: ${human.websiteUrl}`,
                 ].filter(Boolean).join('\n');
+                // Reachability info for agents
+                const channels = human.activeChannels || [];
+                const chCount = human.channelCount ?? channels.length;
+                const reachabilityLabel = chCount >= 3 ? 'Highly reachable' : chCount >= 2 ? 'Reachable' : chCount >= 1 ? 'Limited reachability' : 'Low reachability';
+                const channelList = channels.length > 0 ? channels.map(c => c.charAt(0).toUpperCase() + c.slice(1)).join(', ') : 'None configured';
                 const details = `# ${human.name}${human.username ? ` (@${human.username})` : ''} — Full Profile
 
+## Reachability — ${reachabilityLabel} (${chCount}/4 channels)
+Active channels: ${channelList}
+_Humans with more notification channels respond faster to job offers._
+
 ## Contact
 - Email: ${human.contactEmail || 'Not provided'}
 - Telegram: ${human.telegram || 'Not provided'}
@@ -1584,7 +2121,9 @@ ${fiatInfo || 'No fiat payment methods listed'}
 ${(human.fiatPaymentMethods || []).length > 0 ? '\n_Note: Fiat payments are self-reported. The human must confirm receipt before the job is marked as paid._' : ''}
 
 ## Social Profiles
-${socialLinks || 'No social profiles added'}`;
+${socialLinks || 'No social profiles added'}
+${(human.educations?.length ?? 0) > 0 ? `\n## Education\n${human.educations.map(e => `- ${e.degree || 'Degree'}${e.field ? ` in ${e.field}` : ''}${e.institution ? `, ${e.institution}` : ''}${e.country ? ` (${e.country})` : ''}${e.endYear ? ` — ${e.endYear}` : e.year ? ` — ${e.year}` : ''}`).join('\n')}` : ''}
+${(human.certificates?.length ?? 0) > 0 ? `\n## Certificates\n${human.certificates.map(c => `- ${c.name || 'Certificate'}${c.issuer ? ` — ${c.issuer}` : ''}${c.year ? ` (${c.year})` : ''}`).join('\n')}` : ''}`;
                 return {
                     content: [{ type: 'text', text: details }],
                 };
@@ -1592,7 +2131,7 @@ ${socialLinks || 'No social profiles added'}`;
             if (name === 'request_activation_code') {
                 const agentKey = args?.agent_key;
                 if (!agentKey) {
-                    throw new Error('agent_key is required.');
+                    throw new Error('agent_key is required. Call register_agent first to get an API key (starts with hp_).');
                 }
                 const res = await fetch(`${API_BASE}/api/agents/activate/social`, {
                     method: 'POST',
@@ -1634,7 +2173,7 @@ ${socialLinks || 'No social profiles added'}`;
             if (name === 'verify_social_activation') {
                 const agentKey = args?.agent_key;
                 if (!agentKey) {
-                    throw new Error('agent_key is required.');
+                    throw new Error('agent_key is required. Call register_agent first to get an API key (starts with hp_).');
                 }
                 const res = await fetch(`${API_BASE}/api/agents/activate/social/verify`, {
                     method: 'POST',
@@ -1666,7 +2205,7 @@ You can now create job offers and view full human profiles using \`get_human_pro
             if (name === 'get_activation_status') {
                 const agentKey = args?.agent_key;
                 if (!agentKey) {
-                    throw new Error('agent_key is required.');
+                    throw new Error('agent_key is required. Call register_agent first to get an API key (starts with hp_).');
                 }
                 const res = await fetch(`${API_BASE}/api/agents/activate/status`, {
                     headers: { 'X-Agent-Key': agentKey },
@@ -1701,7 +2240,7 @@ You can now create job offers and view full human profiles using \`get_human_pro
             if (name === 'get_payment_activation') {
                 const agentKey = args?.agent_key;
                 if (!agentKey) {
-                    throw new Error('agent_key is required.');
+                    throw new Error('agent_key is required. Call register_agent first to get an API key (starts with hp_).');
                 }
                 const res = await fetch(`${API_BASE}/api/agents/activate/payment`, {
                     method: 'POST',
@@ -1737,7 +2276,7 @@ You can now create job offers and view full human profiles using \`get_human_pro
             if (name === 'verify_payment_activation') {
                 const agentKey = args?.agent_key;
                 if (!agentKey) {
-                    throw new Error('agent_key is required.');
+                    throw new Error('agent_key is required. Call register_agent first to get an API key (starts with hp_).');
                 }
                 const res = await fetch(`${API_BASE}/api/agents/activate/payment/verify`, {
                     method: 'POST',
@@ -1773,7 +2312,7 @@ You can now create up to 15 job offers per day and view up to 50 full human prof
             if (name === 'start_stream') {
                 const agentKey = args?.agent_key;
                 if (!agentKey)
-                    throw new Error('agent_key is required.');
+                    throw new Error('agent_key is required. Call register_agent first to get an API key (starts with hp_).');
                 const res = await fetch(`${API_BASE}/api/jobs/${args?.job_id}/start-stream`, {
                     method: 'PATCH',
                     headers: {
@@ -1801,7 +2340,7 @@ You can now create up to 15 job offers per day and view up to 50 full human prof
             if (name === 'record_stream_tick') {
                 const agentKey = args?.agent_key;
                 if (!agentKey)
-                    throw new Error('agent_key is required.');
+                    throw new Error('agent_key is required. Call register_agent first to get an API key (starts with hp_).');
                 const res = await fetch(`${API_BASE}/api/jobs/${args?.job_id}/stream-tick`, {
                     method: 'PATCH',
                     headers: {
@@ -1825,7 +2364,7 @@ You can now create up to 15 job offers per day and view up to 50 full human prof
             if (name === 'pause_stream') {
                 const agentKey = args?.agent_key;
                 if (!agentKey)
-                    throw new Error('agent_key is required.');
+                    throw new Error('agent_key is required. Call register_agent first to get an API key (starts with hp_).');
                 const res = await fetch(`${API_BASE}/api/jobs/${args?.job_id}/pause-stream`, {
                     method: 'PATCH',
                     headers: {
@@ -1848,7 +2387,7 @@ You can now create up to 15 job offers per day and view up to 50 full human prof
             if (name === 'resume_stream') {
                 const agentKey = args?.agent_key;
                 if (!agentKey)
-                    throw new Error('agent_key is required.');
+                    throw new Error('agent_key is required. Call register_agent first to get an API key (starts with hp_).');
                 const res = await fetch(`${API_BASE}/api/jobs/${args?.job_id}/resume-stream`, {
                     method: 'PATCH',
                     headers: {
@@ -1874,7 +2413,7 @@ You can now create up to 15 job offers per day and view up to 50 full human prof
             if (name === 'stop_stream') {
                 const agentKey = args?.agent_key;
                 if (!agentKey)
-                    throw new Error('agent_key is required.');
+                    throw new Error('agent_key is required. Call register_agent first to get an API key (starts with hp_).');
                 const res = await fetch(`${API_BASE}/api/jobs/${args?.job_id}/stop-stream`, {
                     method: 'PATCH',
                     headers: {
@@ -1897,7 +2436,7 @@ You can now create up to 15 job offers per day and view up to 50 full human prof
             if (name === 'send_job_message') {
                 const agentKey = args?.agent_key;
                 if (!agentKey)
-                    throw new Error('agent_key is required.');
+                    throw new Error('agent_key is required. Call register_agent first to get an API key (starts with hp_).');
                 const res = await fetch(`${API_BASE}/api/jobs/${args?.job_id}/messages`, {
                     method: 'POST',
                     headers: {
@@ -1921,7 +2460,7 @@ You can now create up to 15 job offers per day and view up to 50 full human prof
             if (name === 'get_job_messages') {
                 const agentKey = args?.agent_key;
                 if (!agentKey)
-                    throw new Error('agent_key is required.');
+                    throw new Error('agent_key is required. Call register_agent first to get an API key (starts with hp_).');
                 const res = await fetch(`${API_BASE}/api/jobs/${args?.job_id}/messages`, {
                     headers: { 'X-Agent-Key': agentKey },
                 });
@@ -1946,7 +2485,7 @@ You can now create up to 15 job offers per day and view up to 50 full human prof
             if (name === 'create_listing') {
                 const agentKey = args?.agent_key;
                 if (!agentKey)
-                    throw new Error('agent_key is required.');
+                    throw new Error('agent_key is required. Call register_agent first to get an API key (starts with hp_).');
                 const res = await fetch(`${API_BASE}/api/listings`, {
                     method: 'POST',
                     headers: {
@@ -1961,6 +2500,11 @@ You can now create up to 15 job offers per day and view up to 50 full human prof
                         requiredSkills: args?.required_skills || [],
                         requiredEquipment: args?.required_equipment || [],
                         location: args?.location,
+                        locationStreet: args?.location_street,
+                        locationCountry: args?.location_country,
+                        locationRegion: args?.location_region,
+                        locationLocality: args?.location_locality,
+                        locationPostal: args?.location_postal,
                         locationLat: args?.location_lat,
                         locationLng: args?.location_lng,
                         radiusKm: args?.radius_km,
@@ -2051,7 +2595,7 @@ You can now create up to 15 job offers per day and view up to 50 full human prof
                 const res = await fetch(`${API_BASE}/api/listings/${args?.listing_id}`);
                 if (!res.ok) {
                     if (res.status === 404)
-                        throw new Error(`Listing not found: ${args?.listing_id}`);
+                        throw new Error(`Listing not found: "${args?.listing_id}". Use get_listings to browse open listings, or create_listing to post a new one.`);
                     throw new Error(`API error: ${res.status}`);
                 }
                 const listing = await res.json();
@@ -2089,7 +2633,7 @@ ${agent?.websiteUrl ? `- **Website:** ${agent.websiteUrl}` : ''}
             if (name === 'get_listing_applications') {
                 const agentKey = args?.agent_key;
                 if (!agentKey)
-                    throw new Error('agent_key is required.');
+                    throw new Error('agent_key is required. Call register_agent first to get an API key (starts with hp_).');
                 const res = await fetch(`${API_BASE}/api/listings/${args?.listing_id}/applications`, {
                     headers: { 'X-Agent-Key': agentKey },
                 });
@@ -2126,7 +2670,7 @@ ${agent?.websiteUrl ? `- **Website:** ${agent.websiteUrl}` : ''}
             if (name === 'make_listing_offer') {
                 const agentKey = args?.agent_key;
                 if (!agentKey)
-                    throw new Error('agent_key is required.');
+                    throw new Error('agent_key is required. Call register_agent first to get an API key (starts with hp_).');
                 const res = await fetch(`${API_BASE}/api/listings/${args?.listing_id}/applications/${args?.application_id}/offer`, {
                     method: 'POST',
                     headers: {
@@ -2150,7 +2694,7 @@ ${agent?.websiteUrl ? `- **Website:** ${agent.websiteUrl}` : ''}
             if (name === 'cancel_listing') {
                 const agentKey = args?.agent_key;
                 if (!agentKey)
-                    throw new Error('agent_key is required.');
+                    throw new Error('agent_key is required. Call register_agent first to get an API key (starts with hp_).');
                 const res = await fetch(`${API_BASE}/api/listings/${args?.listing_id}`, {
                     method: 'DELETE',
                     headers: { 'X-Agent-Key': agentKey },
@@ -2207,7 +2751,7 @@ ${agent?.websiteUrl ? `- **Website:** ${agent.websiteUrl}` : ''}
             if (name === 'leave_review') {
                 const res = await fetch(`${API_BASE}/api/jobs/${args?.job_id}/review`, {
                     method: 'POST',
-                    headers: { 'Content-Type': 'application/json' },
+                    headers: { 'Content-Type': 'application/json', 'X-Agent-Key': args?.agent_key },
                     body: JSON.stringify({
                         rating: args?.rating,
                         comment: args?.comment,
@@ -2232,8 +2776,156 @@ Thank you for your feedback. This helps build the human's reputation.`,
                     ],
                 };
             }
+            // ======================== ESCROW TOOLS ========================
+            if (name === 'list_arbitrators') {
+                const res = await fetch(`${API_BASE}/api/escrow/arbitrators`);
+                if (!res.ok) {
+                    const error = await res.json();
+                    throw new Error(error.error || 'Escrow not enabled on this server');
+                }
+                const arbitrators = await res.json();
+                if (arbitrators.length === 0) {
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: 'No arbitrators available yet. The platform is onboarding vetted arbitrators. Check back soon or contact the platform owner.',
+                            }],
+                    };
+                }
+                const list = arbitrators.map((a) => `- **${a.name}** (${a.id})
+  Fee: ${a.arbitratorFeeBps / 100}% | Specialties: ${a.arbitratorSpecialties?.join(', ') || 'General'} | SLA: ${a.arbitratorSla || 'N/A'}
+  Disputes: ${a.arbitratorDisputeCount} resolved | Wallet: ${a.wallets?.[0]?.address || 'Not set'}`).join('\n');
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `**Available Arbitrators (${arbitrators.length})**\n\n${list}\n\nUse the wallet address as \`escrow_arbitrator_address\` in \`create_job_offer\` with \`payment_mode: "ESCROW"\`.`,
+                        }],
+                };
+            }
+            if (name === 'register_as_arbitrator') {
+                const agentKey = args?.agent_key;
+                if (!agentKey)
+                    throw new Error('agent_key is required');
+                // Get agent profile to find ID
+                const profileRes = await fetch(`${API_BASE}/api/agents/me`, {
+                    headers: { 'X-Agent-Key': agentKey },
+                });
+                if (!profileRes.ok)
+                    throw new Error('Invalid agent key');
+                const agent = await profileRes.json();
+                // Update agent with arbitrator fields
+                const res = await fetch(`${API_BASE}/api/agents/${agent.id}/arbitrator`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'X-Agent-Key': agentKey,
+                    },
+                    body: JSON.stringify({
+                        feeBps: args?.fee_bps,
+                        specialties: args?.specialties,
+                        sla: args?.sla,
+                        webhookUrl: args?.webhook_url,
+                        walletSig: args?.wallet_signature,
+                    }),
+                });
+                if (!res.ok) {
+                    const error = await res.json();
+                    throw new Error(error.error || 'Failed to register as arbitrator');
+                }
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `**Registered as Arbitrator!**
+
+Your agent "${agent.name}" is now listed as an arbitrator candidate. The platform owner will review and whitelist your wallet on the escrow contract.
+
+**Fee:** ${args?.fee_bps / 100}%
+**Webhook:** ${args?.webhook_url}
+**Specialties:** ${args?.specialties?.join(', ') || 'General'}
+
+**Next:** Wait for platform approval. Once whitelisted, payers can select you as arbitrator. Your fee is passed by the payer at deposit time — no on-chain setup needed from you.`,
+                        }],
+                };
+            }
+            if (name === 'get_dispute_details') {
+                const agentKey = args?.agent_key;
+                if (!agentKey)
+                    throw new Error('agent_key is required');
+                const res = await fetch(`${API_BASE}/api/escrow/${args?.job_id}/status`);
+                if (!res.ok) {
+                    const error = await res.json();
+                    throw new Error(error.error || 'Failed to get dispute details');
+                }
+                const escrow = await res.json();
+                // Also get job messages as evidence
+                const msgRes = await fetch(`${API_BASE}/api/jobs/${args?.job_id}/messages`, {
+                    headers: { 'X-Agent-Key': agentKey },
+                });
+                const messages = msgRes.ok ? await msgRes.json() : [];
+                const jobRes = await fetch(`${API_BASE}/api/jobs/${args?.job_id}`);
+                const job = jobRes.ok ? await jobRes.json() : null;
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `**Dispute Details for Job ${args?.job_id}**
+
+**Title:** ${job?.title || 'N/A'}
+**Description:** ${job?.description || 'N/A'}
+**Price:** $${job?.priceUsdc || 'N/A'}
+**Status:** ${escrow.escrowStatus}
+**Escrowed Amount:** $${escrow.escrowAmount || 'N/A'}
+**Dispute Reason:** ${job?.disputeReason || 'Not specified'}
+**Disputed At:** ${escrow.escrowDisputedAt || 'N/A'}
+**Arbitrator Fee Rate:** ${escrow.escrowArbitratorFeeBps / 100}%
+
+**Messages (${messages.length}):**
+${messages.map((m) => `[${m.senderType}] ${m.content}`).join('\n') || 'No messages'}
+
+**Your Task:** Review the evidence and submit a verdict using \`submit_verdict\`. Split the escrowed amount between payee and depositor. Your fee is automatically calculated from your locked rate.`,
+                        }],
+                };
+            }
+            if (name === 'submit_verdict') {
+                const agentKey = args?.agent_key;
+                if (!agentKey)
+                    throw new Error('agent_key is required');
+                const res = await fetch(`${API_BASE}/api/escrow/resolve`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'X-Agent-Key': agentKey,
+                    },
+                    body: JSON.stringify({
+                        jobId: args?.job_id,
+                        toPayee: args?.to_payee,
+                        toDepositor: args?.to_depositor,
+                        arbitratorFee: args?.arbitrator_fee,
+                        nonce: args?.nonce,
+                        signature: args?.signature,
+                    }),
+                });
+                if (!res.ok) {
+                    const error = await res.json();
+                    throw new Error(error.error || 'Failed to submit verdict');
+                }
+                const result = await res.json();
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `**Verdict Submitted!**
+
+**Job:** ${args?.job_id}
+**To Worker:** $${Number(args?.to_payee) / 1e6}
+**To Payer:** $${Number(args?.to_depositor) / 1e6}
+**Your Fee:** $${Number(args?.arbitrator_fee) / 1e6}
+**Tx Hash:** ${result.resolveTxHash}
+
+The escrow has been resolved on-chain. Funds will be distributed to the respective parties.`,
+                        }],
+                };
+            }
             return {
-                content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+                content: [{ type: 'text', text: `Unknown tool: "${name}". Available tools: search_humans, get_human, get_human_profile, register_agent, create_job_offer, get_job_status, mark_job_paid, approve_completion, request_revision, leave_review, send_job_message, get_job_messages, create_listing, get_listings, get_listing, get_listing_applications, make_listing_offer, cancel_listing, list_arbitrators, register_as_arbitrator, get_dispute_details, submit_verdict, and more. Start with search_humans or register_agent.` }],
                 isError: true,
             };
         }