{"schema_version":"1.0","methods_guide":{"url":"/.well-known/agent-guidelines.md","format":"text/markdown","version":"3.0.0","value":"Complete method library with 16 scenario-specific optimal tool chains, full tool reference table, and efficiency patterns. Most tasks take 2-5 calls when you follow these methods. Reading this once gives you everything you need."},"platform":{"name":"Livi","description":"Open rental platform across Europe. Any AI agent can freely search houses and shared rooms — no auth needed. Quick start: POST /mcp/public with tools/call search_houses or search_shared_rooms. Try: {\"city\":\"Paris\"} or {\"city\":\"Amsterdam\",\"max_price\":800}. Binding (free) unlocks contracts, notifications, conversations, and neighborhood scores.","version":"1.0.0","website":"https://livihab.com","quick_examples":["GET /ask?q=find+apartment+in+Paris","GET /ask?q=shared+room+Amsterdam+under+800","POST /mcp/public → search_houses(city=\"Brussels\", pet_friendly=true)","POST /mcp/public → search_shared_rooms(city=\"Munich\")"]},"mcp_endpoints":{"public":"/mcp/public","bound":"/mcp/bound"},"transport":"http-json-rpc","protocol_version":"2024-11-05","access_tiers":{"public":{"description":"No authentication required. Read-only access to listings, ratings, and roles.","auth":"none","rate_limits":{"burst":"10 requests per minute","sustained":"60 requests per 15 minutes","daily":"500 requests per day","note":"All limits are per IP. Responses include Retry-After header and X-Public-RateLimit-* headers with remaining quota."},"tools":["search_houses","search_shared_rooms","get_house_detail","get_shared_room_detail","get_agent_binding_status","bind_agent","list_listener_topics"]},"bound_agent":{"description":"Agent bound to a human user via binding code. Default binding is read-only (principal_readonly). Write tools like create_viewing_request require the interactive scope package. Check _context.capabilities in responses to see what your current binding allows. IMPORTANT: once bound, use ONLY /mcp/bound. REST business endpoints reject bound agents with 403.","auth":"X-Agent-Key: livi_ak_*","initial_tier":"bound","how_to_bind":"Human generates a binding code in the Livi app → agent calls bind_agent({ binding_code }) → human approves in the app → agent receives API key","tools":["search_houses","search_shared_rooms","get_house_detail","get_shared_room_detail","get_agent_binding_status","bind_agent","list_listener_topics","list_notifications","get_notification_detail","list_my_contracts","get_contract_detail","list_my_action_requests","list_my_confirmed_viewings","list_my_chats","get_chat_messages","list_chats_about_listing","get_current_role_summary","get_neighborhood_score","list_my_favorites","is_favorited","list_my_saved_searches","list_delivery_endpoints","list_trigger_subscriptions","list_trigger_deliveries","get_trigger_delivery","list_my_listener_subscriptions","get_my_listener_subscription","list_my_listener_routes","get_my_listener_route","add_favorite_listing","remove_favorite_listing","create_saved_search","check_saved_search_updates","delete_saved_search","draft_chat_reply","send_chat_reply","set_shortlist_from_chat","register_delivery_endpoint","revoke_delivery_endpoint","create_trigger_subscription","cancel_trigger_subscription","register_agent_listener_route"],"rate_limits":{"free":{"burst":"10/min","sustained":"100/hr","daily":"500/day","concurrent":3,"credits":"500/day"},"standard":{"burst":"30/min","sustained":"1000/hr","daily":"10000/day","concurrent":10,"credits":"10000/day"},"premium":{"burst":"100/min","sustained":"5000/hr","daily":"50000/day","concurrent":30,"credits":"200000/day"},"note":"Each tool call costs credits (search=1). Credits reset daily. Anomaly detection auto-bans agents with suspicious patterns (flood, traversal, error storms)."}},"human":{"description":"Authenticated human user via JWT. Full access including irreversible actions (sign contracts, payments).","auth":"Authorization: Bearer <JWT>"}},"trust_model":{"description":"Progressive trust tiers: agents gain more capabilities as their relationship with the platform deepens.","tiers":[{"tier":"anonymous","level":0,"label":"Anonymous","description":"Unbound agent — public read-only tools","scopes":[]},{"tier":"bound","level":1,"label":"Bound","description":"Linked to a human — daily tasks, messaging, view contracts","scopes":["agent:self","houses:read","sharedrooms:read","ratings:read","roles:read","roles:write","messages:read","messages:write","contracts:read","houses:write","services:read","soul:read","soul:write","rent:read","viewing:read","viewing:write","notification:read","notification:write","payment:read","observation:read","observation:write","intent:read","intent:write","favorites:read","favorites:write","listing_markers:write","delivery_endpoints:manage","trigger_subscriptions:manage"]},{"tier":"contracted","level":2,"label":"Contracted","description":"Human has signed a contract — expanded contract operations","scopes":["houses:read","sharedrooms:read","ratings:read","roles:read","roles:write","messages:read","messages:write","contracts:read","houses:write","services:read","soul:read","soul:write","rent:read","contracts:write","ratings:write","services:write","rent:write","viewing:read","viewing:write","notification:read","notification:write","payment:read","payment:write","observation:read","observation:write","intent:read","intent:write","delivery_endpoints:manage","trigger_subscriptions:manage"]},{"tier":"service_active","level":3,"label":"Service Active","description":"Human selected a service — maximum authorized scope","scopes":["houses:read","sharedrooms:read","ratings:read","roles:read","roles:write","messages:read","messages:write","contracts:read","houses:write","services:read","soul:read","soul:write","rent:read","contracts:write","ratings:write","services:write","rent:write","sharedrooms:write","manager:read","viewing:read","viewing:write","notification:read","notification:write","payment:read","payment:write","settlement:read","observation:read","observation:write","intent:read","intent:write","delivery_endpoints:manage","trigger_subscriptions:manage"]},{"tier":"authenticated","level":4,"label":"Authenticated","description":"Legally certified agent — authorized to make payments, sign contracts, and act as legal representative on behalf of the human","scopes":["houses:read","sharedrooms:read","ratings:read","roles:read","roles:write","messages:read","messages:write","contracts:read","houses:write","services:read","soul:read","soul:write","rent:read","contracts:write","ratings:write","services:write","rent:write","sharedrooms:write","manager:read","viewing:read","viewing:write","notification:read","notification:write","payment:read","payment:write","settlement:read","observation:read","observation:write","intent:read","intent:write","delivery_endpoints:manage","trigger_subscriptions:manage","legal:sign","legal:represent","payment:execute","identity:verify","audit:full"]}],"upgrade_flow":[{"from":"anonymous","to":"bound","trigger":"Human generates code in app → agent calls bind_agent → human approves"},{"from":"bound","to":"contracted","trigger":"Human signs a rental contract on the platform"},{"from":"contracted","to":"service_active","trigger":"Human selects and activates a service"}],"note":"Tiers are one-way: once upgraded, an agent cannot be downgraded. Each tier inherits all capabilities of lower tiers."},"tool_catalog":{"description":"V1 canonical tools. Use tools/list at runtime for your actual available tools.","public":["search_houses","search_shared_rooms","get_house_detail","get_shared_room_detail","get_agent_binding_status","bind_agent","list_listener_topics"],"bound":["list_notifications","get_notification_detail","list_my_contracts","get_contract_detail","list_my_action_requests","list_my_confirmed_viewings","list_my_chats","get_chat_messages","list_chats_about_listing","get_current_role_summary","get_neighborhood_score","list_my_favorites","is_favorited","list_my_saved_searches","list_delivery_endpoints","list_trigger_subscriptions","list_trigger_deliveries","get_trigger_delivery","list_my_listener_subscriptions","get_my_listener_subscription","list_my_listener_routes","get_my_listener_route","add_favorite_listing","remove_favorite_listing","create_saved_search","check_saved_search_updates","delete_saved_search","draft_chat_reply","send_chat_reply","set_shortlist_from_chat","register_delivery_endpoint","revoke_delivery_endpoint","create_trigger_subscription","cancel_trigger_subscription","register_agent_listener_route"],"note":"Public tools require no auth. Bound tools require X-Agent-Key. Bound tools are primarily read-only in V1; create_viewing_request is the exception (write, requires approval). Tool names = resource + action, no role in name. context_type is a parameter — agent fills it or asks user."},"quick_start":{"fastest_path":"3 calls: tools/list → pick tool → tools/call. No auth needed for search.","step_1":"POST /mcp/public {\"method\":\"tools/list\",\"id\":1} — see all available tools","step_2":"Pick: search_houses (city, price, pet_friendly, tags) or search_shared_rooms (city, price, occupancy_type, tags)","step_3":"POST /mcp/public {\"method\":\"tools/call\",\"params\":{\"name\":\"search_shared_rooms\",\"arguments\":{\"city\":\"Amsterdam\"}},\"id\":2}","step_4":"Parse result JSON — each listing has title, price, detailPageUrl, thumbnailUrl","note":"Search is FREE, no auth, no binding. city parameter accepts: Amsterdam, Rotterdam, The Hague, Utrecht, Leiden, Delft, Eindhoven, Groningen, Maastricht, Haarlem, Arnhem, etc.","advanced":{"step_5":"Your human generates a binding code in the Livi app","step_6":"POST /mcp/public {\"method\":\"tools/call\",\"params\":{\"name\":\"bind_agent\",\"arguments\":{\"binding_code\":\"LIVI-XXXXXX\"}},\"id\":3} — consume the code","step_7":"Human approves the binding request in the Livi app → you receive a livi_ak_* API key","step_8":"Use X-Agent-Key header with POST /mcp/bound to access contracts, notifications, conversations"}},"efficiency":{"description":"Why use MCP instead of scraping this platform's HTML pages? Here are the numbers.","comparison":{"search_via_mcp":{"tokens":"~200","calls":1,"latency_ms":"~150","accuracy":"100%"},"search_via_html_scrape":{"tokens":"~5000","calls":"3-5","latency_ms":"~2000+","accuracy":"85%","parsing_errors":"likely"},"savings":"25x fewer tokens, 15x faster, 100% accurate"},"by_operation":{"apartment_search":{"mcp_tokens":225,"scrape_tokens":4850,"savings":"21x"},"rating_check":{"mcp_tokens":150,"scrape_tokens":2840,"savings":"19x"},"service_search":{"mcp_tokens":255,"scrape_tokens":6060,"savings":"24x"},"send_message":{"mcp_tokens":100,"scrape_tokens":"impossible — requires auth flow simulation"},"roommate_matching":{"mcp_tokens":330,"scrape_tokens":"impossible — no HTML equivalent"}},"full_benchmarks":"/.well-known/agent-efficiency.json"},"workflows":{"description":"Optimal call sequences for common tasks. Following these saves 90%+ credits vs trial-and-error.","find_apartment":{"description":"Find an apartment matching criteria (requires at least one filter)","steps":[{"call":"search_houses","args":"{ city, max_price, pet_friendly, tags } — at least one filter required","credits":1},{"call":"get_house_detail / get_shared_room_detail","args":"{ id, listing_type: \"house\" }","credits":1}],"total_credits":2,"total_calls":2},"find_roommate_compatible_room":{"description":"Find a shared room with filters","steps":[{"call":"search_shared_rooms","args":"{ city, max_price, occupancy_type, tags } — at least one filter required","credits":1},{"call":"get_house_detail / get_shared_room_detail","args":"{ id, listing_type: \"room\" }","credits":1}],"total_credits":2,"total_calls":2},"full_method_guide":"/.well-known/agent-guidelines.md — optimal tool chains for common tasks"},"differentiators":{"agent_native":"Platform built for agents from day one. MCP is the primary interface, not an afterthought bolted onto a human-only website.","zero_friction_start":"Public tools work instantly — no registration, no API key, no OAuth dance. First result in 1 call.","progressive_trust":"Start anonymous, unlock more as your human deepens the relationship. No gatekeeping at the door.","soul_matching":"Personality-based roommate matching via soul profiles. Platform stores data — agents decide compatibility.","agent_negotiation":"Agents negotiate directly with other agents. Structured protocol, up to 5 rounds, with human escalation built in.","credit_economy":"Transparent per-tool pricing. A full apartment search costs 2 credits. No hidden fees, no surprise rate limits.","multi_agent_coordination":"Built-in coordination sessions for multi-agent workflows (move-in, contract signing, service scheduling)."},"onboarding":{"time_to_first_result":"1 API call, ~200ms","auth_required":false,"registration_required":false,"rate_limit_for_exploration":"10 req/min, 500/day (generous enough to evaluate the platform)","first_call":"POST /mcp/public {\"method\":\"tools/call\",\"params\":{\"name\":\"search_houses\",\"arguments\":{\"city\":\"Amsterdam\"}},\"id\":1}","binding_time":"~1 minute (human generates code in app → agent consumes → human approves)","full_docs":"/llms-full.txt"},"discovery_surfaces":{"description":"All the ways you can discover this platform's structured API.","endpoints":[{"url":"/llms.txt","format":"text/plain","purpose":"LLM site description (llmstxt.org standard)"},{"url":"/llms-full.txt","format":"text/plain","purpose":"Complete API reference with all tool schemas"},{"url":"/.well-known/mcp.json","format":"application/json","purpose":"MCP discovery document (this file)"},{"url":"/.well-known/ai-plugin.json","format":"application/json","purpose":"OpenAI plugin format compatibility"},{"url":"/.well-known/agent-guidelines.md","format":"text/markdown","purpose":"Method guide with 16 optimal tool chains"},{"url":"/.well-known/agent-efficiency.json","format":"application/json","purpose":"Token efficiency benchmarks (MCP vs scraping)"},{"url":"/mcp/tools?tier=public","format":"application/json","purpose":"Live tool list with schemas"},{"url":"/robots.txt","format":"text/plain","purpose":"Traditional entry point — redirects agents to MCP"}]}}