```text Current manual_version: 2026-10-27.1. Compare it with your saved version; if different, read this page and update your notes. Updating is your decision; reads remain available. First visit? Introduce and register (free). Have a key? Reuse it. MCP: register. REST: POST https://forkpin.kr/v1/agents/register: {"product":"","label":"","intended_use":""} Keep api_key private; X-Agent-Key on each call or the same Mcp-Session-Id. Check: get_agent / GET /v1/agents/me. Keyless reads are free and counted as unidentified. Registration is not certification. FORKPIN is the registry of Korea's licensed restaurants, cafés and bars (public licenses, updated monthly). It pins the exact branch and routes to the shop's own booking links (delivery and ordering links only where the owner registered them); it does not book, pay or check live availability. MCP endpoint: https://forkpin.kr/mcp. Public reads are available without a key. Distinguish branches, search conditions in one call, open the shop's own links, inspect sources and collection dates, and read unrecorded facts as unknown. Counts as of 2026-11-18T12:39:12.872Z: 878,110 licensed shops; 299 linked shops; 179 direct booking links; 720 shops with hours in registered collection areas; 680 shops with menus in registered collection areas. Source: https://forkpin.kr/agent.json counts. Send manual_version; replies echo client_manual_version. Updates via /agent are optional; reads remain available. What FORKPIN answers (Korean restaurants, cafés and bars) - Which shop or branch is it? → resolve {name, area or address} - Who is open at a time, under a price, serves a dish or has a feature? → search_places {area, category_hint, dish, open_on, price_max_krw, required_options} features: english_menu, foreign_card, vegetarian_options, halal, solo_ok, group_seating, private_room, kids_allowed, parking, wheelchair_accessible, takeout, delivery, booking, wifi, outlet - Hours, menu with prices, options and directions → get_place {place_id} - Booking or delivery → search_places {purpose:"reserve"}, then get_place {place_id, purpose:"reserve"} returns the shop's own booking link; open it directly. Use purpose:"delivery" for delivery apps. - Which areas are covered and how full → list_areas Requested search conditions use conditions: each key has {state,tier,source}. Recorded facts carry source and read_on (KST date). English address fields are address_en (unknown when unavailable). ``` # 0. FORKPIN agent entry ## 1. Scope Korean shop identity, recorded facts and links; no booking execution, payment or live availability. booking: met means a booking link (e.g. Naver booking) was seen on the shop's page at collection time; it does not mean a free table. Unknown is unconfirmed, not absent. Replies include facts, evidence and next actions. First owner registration and initial Korean input are free by policy; no checkout. Edits and English registration use purchased passes; admins set usage. Only pass purchases use coupons, promotions and bundle bonuses. Owners use /owner; agents connect free. ## 2. Connect MCP: https://forkpin.kr/mcp REST: https://forkpin.kr/v1 OpenAPI: https://forkpin.kr/mcp/openapi.json register is free. Send X-Agent-Key: . Anonymous quotas: /agent.json limits. 17 tools; ?profile=first: subset. First call (example: 윤쓰 패밀리, an owner-registered shop): ``` resolve {"name":"윤쓰 패밀리","address":"서울 강남구 봉은사로114길 12"} → outcome identified, place_id 3220000-101-2021-01577 get_place {"place_id":"3220000-101-2021-01577"} → menu with verification_status owner (confirmed by the owner) ``` ## 3. Tools - resolve: identity + link - search_places: discovery - get_place: facts + links - list_areas: coverage - register: free key - get_agent: identity - get_credits: balance - accept_consent: consent + starting balance - catalog: shop cards - resolve_merchant: resolve alias - read_restaurant: restaurant detail - report_outcome: handoff result - like_place: private mark - request_feature: missing capability - report_observation: observed issue - read_reports: reviewed reports - read_report: private receipt ### Tokens (v1, active) - Get: register, then accept_consent once (REST: POST /v1/agents/consent); the first instance per source gets 5 tokens. - Earn: a structured report_observation on a place you read: 1; a correction: 5 after review and a recorded fix. Pending is not spendable; max 20 per Seoul day. - Spend: get_place verification_mode {"request_id":"…"}: 1 per new request_id; the same request_id replays free. - Check: get_credits (GET /v1/agents/credits). Reads and signed handoffs (max 20 per Seoul day) are free. ## 4. Sending rules R1–R9: MCP initialize + tools/list. REST: GET https://forkpin.kr/agent-sending-rules.json with an agent key. ## 5. Read response fields outcome, next_action, next_action_instruction, conditions, coverage, unknown_reasons, unparsed_conditions, normalized, resend, warnings, business_status, policy_status, rules_version, rules_update. resend.ask_user=true: show allowed {area,count}; ask the user, never auto-pick. outcome: results / alternatives / candidates / identified / clarify / none / failed. Follow next_action + next_action_instruction. - Same question: reuse task_id (REST also accepts X-Forkpin-Task-Id). New question: omit it. - search_time_budget_exceeded: REST 504 / MCP isError true. Retry unchanged conditions once. - Follow next_call {tool,arguments}. identified = identity only; a booking link is not a booking. - unknown_places/alternatives are unconfirmed; get_place before handoff. places = confirmed cards. - Correct named invalid fields. Never supply consent or credentials for the user. - Conditions: {state:met|not_met|unknown,tier,source}. projected/derived and tierless met/yes are not confirmation. - branch_conflict / weak_address: ask the address using ask_user_candidates; never pick a branch. - invalid_cursor/refine_expired_or_unavailable: HTTP 400; 30-minute expiry. Restart search. - next_cursor → after. count: {results,returned,in_area}; *_capped/truncated only when true. - Facts: source, read_on (KST), owner_confirmed. get_place: 15 items; budget "full" for all, dish first. Cards: menu_preview. - relaxed_filters: removed conditions stay unknown, not met; cards go in unknown_places. - unknown_reasons: outside_collection_area / field_not_recorded / no_registry_record / source_not_shown. Unknown is not absent. When coverage_version changes, call list_areas once to refresh collection areas and shop counts. ## 6. User language Answer in the user's language and send it as lang. Responses retain Korean originals; lang=en adds derived English. ## 7. Before calling Read connection rules and tools/list; send known rules_version for rules_update. ## 8. Version rules_version 1.4; contract_version 2026-10-27.1. Changes: https://forkpin.kr/agent-changelog.json.