{"openapi":"3.1.0","info":{"title":"Fine Structure API","version":"1.0.0","summary":"Build, edit, validate and publish complete web applications with AI.","description":"Fine Structure is an AI software-building platform: it generates complete applications, runs autonomous AI agent teams, and maintains a business brain over your data.\n\nGetting started is self-serve: sign up free at https://finestructure.ai (free tier included, no credit card), then create an API/MCP token at https://finestructure.ai/api-keys and pass it as `Authorization: Bearer fse2_mcp_<token>`.\n\nEvery operation below is also available as an MCP tool via the JSON-RPC endpoint POST /api/mcp (Streamable HTTP transport).","termsOfService":"https://finestructure.ai/terms","contact":{"name":"Fine Structure support","email":"support@finestructure.ai","url":"https://finestructure.ai/contact"}},"servers":[{"url":"https://finestructure.ai","description":"Production"}],"tags":[{"name":"tools","description":"Per-tool REST operations (one per Fine Structure tool)"},{"name":"bridge","description":"Generic call-by-name REST bridge"},{"name":"mcp","description":"Model Context Protocol (JSON-RPC 2.0)"},{"name":"discovery","description":"Unauthenticated discovery and health endpoints"}],"paths":{"/api/mcp/tools/{tool_name}":{"post":{"operationId":"call_tool_generic","summary":"Call any Fine Structure tool by name","description":"Generic REST bridge to the Fine Structure tool surface. The request body is the tool's arguments object. Prefer the per-tool operations below, which carry the exact JSON schema for each tool.","tags":["bridge"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"tool_name","in":"path","required":true,"schema":{"type":"string"},"description":"Name of the tool to execute (see the per-tool operations or GET /api/mcp/manifest)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp":{"post":{"operationId":"mcp_jsonrpc","summary":"MCP JSON-RPC 2.0 endpoint (initialize, tools/list, tools/call)","description":"Model Context Protocol endpoint over Streamable HTTP. Supports the methods initialize, tools/list and tools/call per the MCP specification.","tags":["mcp"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcRequest"}}}},"responses":{"200":{"description":"JSON-RPC 2.0 response (success or error object)","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/mcp/manifest":{"get":{"operationId":"get_manifest","summary":"Tool discovery manifest (all tool names, descriptions and JSON schemas)","tags":["discovery"],"security":[],"responses":{"200":{"description":"Manifest with every available tool definition","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/mcp/health":{"get":{"operationId":"health_check","summary":"Service health check","tags":["discovery"],"security":[],"responses":{"200":{"description":"Service is up","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/mcp/tools/create_app":{"post":{"operationId":"create_app","summary":"Create a new application from a natural language prompt","description":"Create a new application from a natural language prompt. The AI generates a complete web app with pages, components, styling, and data models. Returns a job_id - poll get_job_status to track progress. When the job is done, the app is ready.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Name for the app (1-100 chars)"},"prompt":{"type":"string","description":"Detailed description of the app to build"},"description":{"type":"string","description":"Optional short description","default":""}},"required":["name","prompt"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/agency_create_client":{"post":{"operationId":"agency_create_client","summary":"Agency mode only","description":"Agency mode only. Create or update a client record for an account-level agent. This does not create a verified Fine Structure user account and does not transfer ownership.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"client_email":{"type":"string","description":"Client email that will be allowed to claim projects"},"client_full_name":{"type":"string","description":"Optional client display name","default":""},"note":{"type":"string","description":"Optional internal note for the agency","default":""}},"required":["client_email"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/agency_list_clients":{"post":{"operationId":"agency_list_clients","summary":"Agency mode only","description":"Agency mode only. List client records and app handoff status for the authenticated agent.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"include_handoffs":{"type":"boolean","description":"Include claim links status without raw tokens","default":true}}}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/agency_create_client_app":{"post":{"operationId":"agency_create_client_app","summary":"Agency mode only","description":"Agency mode only. Create a new app owned by the agent, start generation, and create a claim link for the client. Ownership transfers only when the invited client logs in with the same email and accepts the claim link.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"client_email":{"type":"string","description":"Client email allowed to claim ownership"},"client_full_name":{"type":"string","description":"Optional client display name","default":""},"name":{"type":"string","description":"Name for the app (1-100 chars)"},"prompt":{"type":"string","description":"Detailed description of the app to build"},"description":{"type":"string","description":"Optional short app description","default":""},"note":{"type":"string","description":"Optional internal client/project note","default":""},"keep_agent_collaborator":{"type":"boolean","description":"After claim, invite the agent back as an editor collaborator","default":true},"claim_expires_in_days":{"type":"integer","description":"Claim link lifetime, 1-90 days","default":14}},"required":["client_email","name","prompt"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/agency_create_claim_link":{"post":{"operationId":"agency_create_claim_link","summary":"Agency mode only","description":"Agency mode only. Create a client claim link for an existing app owned by the agent. The client must log in with the invited email before ownership transfers.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"Existing app ID owned by the agent"},"client_email":{"type":"string","description":"Client email allowed to claim ownership"},"client_full_name":{"type":"string","description":"Optional client display name","default":""},"note":{"type":"string","description":"Optional internal note","default":""},"keep_agent_collaborator":{"type":"boolean","description":"Invite agent as editor after claim","default":true},"claim_expires_in_days":{"type":"integer","description":"Claim link lifetime, 1-90 days","default":14}},"required":["app_id","client_email"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/agency_get_claim_status":{"post":{"operationId":"agency_get_claim_status","summary":"Agency mode only","description":"Agency mode only. Inspect one handoff status without exposing the raw claim token.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"handoff_id":{"type":"string","description":"Handoff ID returned by agency_create_claim_link or agency_create_client_app"}},"required":["handoff_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/update_app":{"post":{"operationId":"update_app","summary":"Update an existing application with a new prompt","description":"Update an existing application with a new prompt. The AI modifies the app based on your instructions. Creates a Saved Version before the update. Returns a job_id - poll get_job_status to track progress.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID to update"},"prompt":{"type":"string","description":"What to change in the app"}},"required":["app_id","prompt"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/publish_app":{"post":{"operationId":"publish_app","summary":"Publish an app - freeze current state and make it live at a URL","description":"Publish an app - freeze current state and make it live at a URL. Also configures whether the public URL is open, app-login gated, private, or inferred from the app.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID to publish"},"access_mode":{"type":"string","enum":["infer","public_open","public_auth","private","keep"],"default":"infer","description":"Live access policy. public_open = anyone can view. public_auth = public URL opens but app login is required. private = published snapshot remains owner/collaborator-only. keep = preserve current visibility/auth settings. infer = choose from existing settings and obvious app structure."},"auth_required":{"type":"boolean","description":"Optional explicit override for generated-app login requirement. Prefer access_mode when possible."},"make_public":{"type":"boolean","description":"Optional explicit override for whether published URLs are publicly reachable. Prefer access_mode when possible."}},"required":["app_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/get_platform_guide":{"post":{"operationId":"get_platform_guide","summary":"Return a machine-readable Fine Structure / FSe2 guide for AI agents","description":"Return a machine-readable Fine Structure / FSe2 guide for AI agents. Call this at the start of an MCP session to learn app files, entities, safe edit workflows, validation, publishing, A/B testing, secrets, and platform rules.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"Optional app ID. If provided, the guide includes a safe app context summary."},"sections":{"type":"array","description":"Optional subset of guide sections to return.","items":{"type":"string","enum":["ab_testing","agency","agents","app_code","checklists","data_model","direct_file_edit","domains","file_model","functions","generation","marketing","media","overview","platform_requests","publishing","saas","safety","sdk","secrets_integrations","security","validation"]}},"task_type":{"type":"string","description":"Optional task hint, for example edit_app, direct_file_edit, seed_data, or publish_app."}}}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/get_recommended_workflow":{"post":{"operationId":"get_recommended_workflow","summary":"Return the recommended MCP tool sequence for a task type","description":"Return the recommended MCP tool sequence for a task type. Use this before creating apps, editing files, seeding data, publishing, setting up A/B tests, restoring versions, or configuring secrets/integrations.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"task_type":{"type":"string","description":"The task type to plan.","enum":["ab_test","agency_client_app","backend_function","create_app","direct_file_edit","domain_setup","edit_app","fix_runtime_error","generate_media","inspect_preview","publish_app","saas_setup","schema_change","secrets_integration","security_setup","seed_data","unknown","version_restore"],"default":"unknown"},"goal":{"type":"string","description":"Optional short description of the user's goal.","default":""},"app_id":{"type":"string","description":"Optional app ID. If provided, the workflow includes a safe app context summary."}}}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/get_job_status":{"post":{"operationId":"get_job_status","summary":"Poll the status of an async generation job","description":"Poll the status of an async generation job. Use this after create_app or update_app to know when the job is done. Returns status ('running' or 'done'), progress events, and result summary when complete.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","description":"The job_id returned by create_app or update_app"}},"required":["job_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/get_app_status":{"post":{"operationId":"get_app_status","summary":"Get app overview: files, published state, URL, active jobs","description":"Get app overview: files, published state, URL, active jobs.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"}},"required":["app_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/get_app_links":{"post":{"operationId":"get_app_links","summary":"Return editor, preview, published path, subdomain, and custom-domain links plus whether each works for anonymous visi...","description":"Return editor, preview, published path, subdomain, and custom-domain links plus whether each works for anonymous visitors, app users, or Studio users based on publish and auth settings.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"}},"required":["app_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/list_app_domains":{"post":{"operationId":"list_app_domains","summary":"List an app's platform path, subdomain, and configured custom domain with verification, SSL, primary-domain, redirect...","description":"List an app's platform path, subdomain, and configured custom domain with verification, SSL, primary-domain, redirect, publish, and login-gating status.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"}},"required":["app_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/set_app_subdomain":{"post":{"operationId":"set_app_subdomain","summary":"Set or clear the app platform subdomain - the '<subdomain>.<base domain>' host Fine Structure already serves the app on","description":"Set or clear the app platform subdomain - the '<subdomain>.<base domain>' host Fine Structure already serves the app on. Runs the same ownership, format, reserved-name and uniqueness checks as the Studio subdomain field because it calls the same model function. Replacing a subdomain takes effect immediately and creates NO redirect: the previous name stops resolving to this app and is released for anyone to claim. Pass an empty subdomain to clear it. For a domain the user owns, use add_custom_domain instead.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"subdomain":{"type":"string","description":"Subdomain label: 3-32 characters, lowercase letters, digits and hyphens, no leading or trailing hyphen, not a reserved platform name. Empty string clears the subdomain."}},"required":["app_id","subdomain"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/check_subdomain_available":{"post":{"operationId":"check_subdomain_available","summary":"Check whether a platform subdomain can be claimed before calling set_app_subdomain","description":"Check whether a platform subdomain can be claimed before calling set_app_subdomain. Returns available plus a status of available, invalid, reserved, taken, current, or empty, with the exact reason. Pass app_id (an app you own) to have that app's own current subdomain reported as 'current' instead of 'taken'.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subdomain":{"type":"string","description":"Subdomain label to check"},"app_id":{"type":"string","description":"Optional ID of an app you own. When supplied, this app's own subdomain reports as 'current' instead of 'taken'."}},"required":["subdomain"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/add_custom_domain":{"post":{"operationId":"add_custom_domain","summary":"Attach or replace the app custom domain through the same Fine Structure Studio custom-domain flow","description":"Attach or replace the app custom domain through the same Fine Structure Studio custom-domain flow. Returns exact DNS verification and routing records for the user to configure at their DNS provider.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"domain":{"type":"string","description":"Custom domain to connect, for example example.com or app.example.com"}},"required":["app_id","domain"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/get_domain_verification":{"post":{"operationId":"get_domain_verification","summary":"Return the exact DNS records and instructions required to verify and route the app custom domain","description":"Return the exact DNS records and instructions required to verify and route the app custom domain.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"domain":{"type":"string","description":"Optional configured custom domain. If omitted, uses the app's current custom domain."}},"required":["app_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/check_domain_verification":{"post":{"operationId":"check_domain_verification","summary":"Check Fine Structure custom-domain verification and SSL status for the configured custom domain, then save the latest...","description":"Check Fine Structure custom-domain verification and SSL status for the configured custom domain, then save the latest status.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"domain":{"type":"string","description":"Optional configured custom domain. If omitted, uses the app's current custom domain."}},"required":["app_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/set_primary_domain":{"post":{"operationId":"set_primary_domain","summary":"Set which app host should be treated as primary for generated links and custom-domain redirects","description":"Set which app host should be treated as primary for generated links and custom-domain redirects.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"domain":{"type":"string","description":"Primary host, for example example.com, www.example.com, or the app subdomain host."}},"required":["app_id","domain"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/remove_custom_domain":{"post":{"operationId":"remove_custom_domain","summary":"Remove the configured custom domain from the app and clean up the platform-side hostname registration when possible","description":"Remove the configured custom domain from the app and clean up the platform-side hostname registration when possible.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"domain":{"type":"string","description":"Optional configured custom domain. If omitted, removes the current custom domain."}},"required":["app_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/get_domain_ssl_status":{"post":{"operationId":"get_domain_ssl_status","summary":"Return SSL/certificate status and pending certificate validation DNS records for the app custom domain","description":"Return SSL/certificate status and pending certificate validation DNS records for the app custom domain.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"domain":{"type":"string","description":"Optional configured custom domain. If omitted, uses the app's current custom domain."}},"required":["app_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/configure_domain_redirects":{"post":{"operationId":"configure_domain_redirects","summary":"Configure custom-domain redirect policy: primary domain, optional www/root redirect, and HTTPS enforcement","description":"Configure custom-domain redirect policy: primary domain, optional www/root redirect, and HTTPS enforcement.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"primary_domain":{"type":"string","description":"Canonical primary domain, for example example.com"},"redirect_www":{"type":"boolean","description":"Redirect the www/root counterpart to primary_domain","default":true},"force_https":{"type":"boolean","description":"Redirect HTTP custom-domain requests to HTTPS","default":true}},"required":["app_id","primary_domain"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/list_apps":{"post":{"operationId":"list_apps","summary":"List owned and accepted Studio-shared applications, newest activity first","description":"List owned and accepted Studio-shared applications, newest activity first. Returns up to `limit` apps per call plus the total count; page with `offset` when the account has more. Accepted editors can edit shared source; viewers can read it. Publishing, records, domains and security administration remain owner-only.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"integer","description":"Max apps to return (1-200)","default":50},"offset":{"type":"integer","description":"Apps to skip, for paging","default":0}}}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/get_app_files":{"post":{"operationId":"get_app_files","summary":"Get the file tree for an app with paths and byte sizes","description":"Get the file tree for an app with paths and byte sizes.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"}},"required":["app_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/read_app_file":{"post":{"operationId":"read_app_file","summary":"Read one source file from an app's virtual filesystem","description":"Read one source file from an app's virtual filesystem. Paths follow the Fine Structure app file API, documented at https://finestructure.ai/api/mcp/docs.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"path":{"type":"string","description":"Virtual file path, for example pages/Home.jsx"},"max_chars":{"type":"integer","description":"Maximum content characters to return","default":200000}},"required":["app_id","path"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/read_app_files":{"post":{"operationId":"read_app_files","summary":"Read several source files from an app's virtual filesystem","description":"Read several source files from an app's virtual filesystem. Paths follow the Fine Structure app file API, documented at https://finestructure.ai/api/mcp/docs.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"paths":{"type":"array","items":{"type":"string"},"description":"Virtual file paths to read"},"max_chars_per_file":{"type":"integer","description":"Maximum characters per file","default":100000}},"required":["app_id","paths"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/write_app_file":{"post":{"operationId":"write_app_file","summary":"Create or replace one file in an app's virtual filesystem","description":"Create or replace one file in an app's virtual filesystem. Creates a Saved Version before changing content. Paths and file model follow the Fine Structure app file API, documented at https://finestructure.ai/api/mcp/docs.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"path":{"type":"string","description":"Virtual file path"},"content":{"type":"string","description":"Complete file contents"},"file_type":{"type":"string","description":"Optional file type override"}},"required":["app_id","path","content"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/patch_app_file":{"post":{"operationId":"patch_app_file","summary":"Patch one file by replacing exact text","description":"Patch one file by replacing exact text. Safer than full overwrite for targeted edits. Creates a Saved Version before changing content. Paths follow the Fine Structure app file API, documented at https://finestructure.ai/api/mcp/docs.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"path":{"type":"string","description":"Virtual file path"},"old_text":{"type":"string","description":"Exact existing text to replace"},"new_text":{"type":"string","description":"Replacement text"},"replace_all":{"type":"boolean","description":"Replace all matches instead of the first match","default":false}},"required":["app_id","path","old_text","new_text"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/rename_app_file":{"post":{"operationId":"rename_app_file","summary":"Rename or move one app source file atomically","description":"Rename or move one app source file atomically. Internally stages an upsert at new_path and a delete at old_path, validates the resulting app state, and creates a Saved Version before applying.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"old_path":{"type":"string","description":"Existing virtual file path to rename"},"new_path":{"type":"string","description":"New virtual file path"},"overwrite":{"type":"boolean","description":"Allow replacing an existing file at new_path","default":false},"force":{"type":"boolean","description":"Apply even if validation reports blocking errors","default":false}},"required":["app_id","old_path","new_path"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/get_app_detail":{"post":{"operationId":"get_app_detail","summary":"Deep introspection of an app: entities, pages, settings, integrations, environment variables, and file structure","description":"Deep introspection of an app: entities, pages, settings, integrations, environment variables, and file structure. Use this to understand what an app contains before updating it.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"}},"required":["app_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/get_entities":{"post":{"operationId":"get_entities","summary":"Get all entity (data model) schemas for an app, with record counts","description":"Get all entity (data model) schemas for an app, with record counts. Each entity has fields, types, and relationships.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"}},"required":["app_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/query_entity":{"post":{"operationId":"query_entity","summary":"Query app data records for one entity with optional exact-match filters","description":"Query app data records for one entity with optional exact-match filters.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"entity":{"type":"string","description":"Entity name, for example Patient"},"filters":{"type":"object","description":"Exact-match field filters","default":{}},"sort":{"type":"string","description":"Sort field, prefix with - for descending","default":"-created_date"},"limit":{"type":"integer","description":"Max records to return","default":100},"offset":{"type":"integer","description":"Pagination offset","default":0}},"required":["app_id","entity"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/seed_entity":{"post":{"operationId":"seed_entity","summary":"Compatibility tool for starter-record creation","description":"Compatibility tool for starter-record creation. Inserts directly for the authenticated app owner; by default it only seeds an empty entity (skip_if_not_empty).","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"entity":{"type":"string","description":"Entity name"},"records":{"type":"array","items":{"type":"object"},"description":"Records to insert"},"mode":{"type":"string","enum":["append","skip_if_not_empty"],"description":"append always inserts; skip_if_not_empty inserts only when the entity is empty","default":"skip_if_not_empty"},"reason":{"type":"string","description":"Why these records should be created","default":""}},"required":["app_id","entity","records"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/create_entity_records":{"post":{"operationId":"create_entity_records","summary":"Create/insert records in one app entity","description":"Create/insert records in one app entity. Executes directly for the authenticated app owner and returns the created record ids.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"entity":{"type":"string","description":"Entity name"},"records":{"type":"array","items":{"type":"object"},"description":"Records to create"},"reason":{"type":"string","description":"Why these records should be created","default":""},"expected_count":{"type":"integer","description":"Optional safety check; the write aborts if the record count differs"}},"required":["app_id","entity","records"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/update_entity_record":{"post":{"operationId":"update_entity_record","summary":"Compatibility tool that updates one record by ID","description":"Compatibility tool that updates one record by ID. Executes directly for the authenticated app owner.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"entity":{"type":"string","description":"Entity name"},"record_id":{"type":"string","description":"Record ID"},"data":{"type":"object","description":"Fields to merge into the record"},"reason":{"type":"string","description":"Why this record should be updated","default":""}},"required":["app_id","entity","record_id","data"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/update_entity_records":{"post":{"operationId":"update_entity_records","summary":"Update exact records","description":"Update exact records. Select explicit record_ids or exact-match filters and provide shared changes, or provide per-record updates. Executes directly for the authenticated app owner; expected_count aborts the write on a mismatch.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"entity":{"type":"string","description":"Entity name"},"record_ids":{"type":"array","items":{"type":"string"},"description":"Exact record IDs to update"},"filters":{"oneOf":[{"type":"object"},{"type":"array","items":{"type":"object"}}],"description":"One exact-match selector or a list of exact-match selectors"},"changes":{"type":"object","description":"Shared fields to merge into every selected record"},"updates":{"type":"array","items":{"type":"object","properties":{"record_id":{"type":"string"},"changes":{"type":"object"}},"required":["record_id","changes"]},"description":"Per-record changes; use instead of shared changes"},"reason":{"type":"string","description":"Why these records should be updated","default":""},"expected_count":{"type":"integer","description":"Required match count safety check, when known"}},"required":["app_id","entity"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/delete_entity_records":{"post":{"operationId":"delete_entity_records","summary":"Delete exact records by ID or exact-match filters","description":"Delete exact records by ID or exact-match filters. Executes directly for the authenticated app owner; pass expected_count as a safety check to abort on a mismatch.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"entity":{"type":"string","description":"Entity name"},"record_ids":{"type":"array","items":{"type":"string"},"description":"Exact record IDs to delete"},"filters":{"oneOf":[{"type":"object"},{"type":"array","items":{"type":"object"}}],"description":"One exact-match selector or a list of exact-match selectors"},"reason":{"type":"string","description":"Why these records should be deleted","default":""},"expected_count":{"type":"integer","description":"Required match count safety check, when known"}},"required":["app_id","entity"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/get_pages":{"post":{"operationId":"get_pages","summary":"Get all pages in an app with their file paths and sizes","description":"Get all pages in an app with their file paths and sizes.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"}},"required":["app_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/get_errors":{"post":{"operationId":"get_errors","summary":"Get recent runtime errors for an app (last 20)","description":"Get recent runtime errors for an app (last 20). Useful for diagnosing issues before updating.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"limit":{"type":"integer","description":"Max errors to return (default 20)","default":20}},"required":["app_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/get_app_analytics":{"post":{"operationId":"get_app_analytics","summary":"Traffic analytics for an app's published site over a chosen window: total views, unique visitors, daily series, top p...","description":"Traffic analytics for an app's published site over a chosen window: total views, unique visitors, daily series, top pages, top referrer domains and device split.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"days":{"type":"integer","description":"Window in days (1-90, default 7)","default":7}},"required":["app_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/get_preview_url":{"post":{"operationId":"get_preview_url","summary":"Return editor preview and published/public URLs for an app","description":"Return editor preview and published/public URLs for an app.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"}},"required":["app_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/list_saved_versions":{"post":{"operationId":"list_saved_versions","summary":"List restorable Saved Versions for an app, including versions created by MCP writes","description":"List restorable Saved Versions for an app, including versions created by MCP writes.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"}},"required":["app_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/restore_saved_version":{"post":{"operationId":"restore_saved_version","summary":"Compatibility endpoint for full Saved Version restore","description":"Compatibility endpoint for full Saved Version restore. MCP cannot execute this operation because it can replace database records without the dedicated in-chat approval flow. Use list_saved_versions and compare_current_to_version for read-only inspection, then ask the authenticated app owner to restore through the Fine Structure UI.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"snapshot_id":{"type":"string","description":"Saved Version snapshot_id to inspect before restoring in the UI"}},"required":["app_id","snapshot_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/create_change_set":{"post":{"operationId":"create_change_set","summary":"Create a staged file change set","description":"Create a staged file change set. Add multiple file changes, validate them as one app state, then apply atomically.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"label":{"type":"string","description":"Optional short label"}},"required":["app_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/add_file_change":{"post":{"operationId":"add_file_change","summary":"Stage one file upsert or delete inside a change set","description":"Stage one file upsert or delete inside a change set. Does not modify the live app until apply_change_set. Paths follow the Fine Structure app file API, documented at https://finestructure.ai/api/mcp/docs.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"change_set_id":{"type":"string","description":"Change set ID"},"path":{"type":"string","description":"Virtual file path"},"content":{"type":"string","description":"Complete file contents for upsert","default":""},"file_type":{"type":"string","description":"Optional file type override","default":""},"operation":{"type":"string","enum":["upsert","delete"],"default":"upsert"}},"required":["app_id","change_set_id","path"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/validate_change_set":{"post":{"operationId":"validate_change_set","summary":"Validate current app files plus staged change set files before applying","description":"Validate current app files plus staged change set files before applying.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"change_set_id":{"type":"string","description":"Change set ID"},"include_runtime_errors":{"type":"boolean","default":true}},"required":["app_id","change_set_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/apply_change_set":{"post":{"operationId":"apply_change_set","summary":"Apply a staged change set to the app","description":"Apply a staged change set to the app. Creates a Saved Version before applying. Blocks on validation errors unless force=true.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"change_set_id":{"type":"string","description":"Change set ID"},"force":{"type":"boolean","description":"Apply even if validation has errors","default":false}},"required":["app_id","change_set_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/discard_change_set":{"post":{"operationId":"discard_change_set","summary":"Discard a pending staged change set without changing app files","description":"Discard a pending staged change set without changing app files.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"change_set_id":{"type":"string","description":"Change set ID"}},"required":["app_id","change_set_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/validate_app":{"post":{"operationId":"validate_app","summary":"Run deterministic app checks: syntax, imports, routes/pages, entity schemas, missing entities, and recorded runtime e...","description":"Run deterministic app checks: syntax, imports, routes/pages, entity schemas, missing entities, and recorded runtime errors.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"include_runtime_errors":{"type":"boolean","default":true}},"required":["app_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/inspect_preview":{"post":{"operationId":"inspect_preview","summary":"Return server-side preview context: URLs, persisted runtime/network errors, static clickable candidates, pages, and e...","description":"Return server-side preview context: URLs, persisted runtime/network errors, static clickable candidates, pages, and explicit live-browser availability.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"route":{"type":"string","description":"Optional route to inspect","default":""},"auth_as":{"type":"string","description":"Optional auth simulation: anonymous","default":""},"auth_as_role":{"type":"string","description":"Optional app role simulation, e.g. staff/admin/customer","default":""}},"required":["app_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/get_app_security_context":{"post":{"operationId":"get_app_security_context","summary":"Return safe security context for one owned app: owner id/email, Studio collaborators, generated-app members, route po...","description":"Return safe security context for one owned app: owner id/email, Studio collaborators, generated-app members, route policies, entity policies, function policies, and recent security audit entries. Does not return secrets and does not grant access to other apps.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"audit_limit":{"type":"integer","default":50}},"required":["app_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/set_route_policy":{"post":{"operationId":"set_route_policy","summary":"Create or update a server-owned route policy for a generated app route","description":"Create or update a server-owned route policy for a generated app route.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"route":{"type":"string","description":"Route or wildcard route, e.g. /admin/*"},"require_auth":{"type":"boolean","default":true},"allowed_roles":{"type":"array","items":{"type":"string"},"description":"Allowed app roles"},"redirect_to":{"type":"string","default":"/Login"}},"required":["app_id","route","require_auth","allowed_roles"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/set_function_policy":{"post":{"operationId":"set_function_policy","summary":"Create or update the server-owned access policy of a backend function (functions/<name>.js)","description":"Create or update the server-owned access policy of a backend function (functions/<name>.js). Without a policy a function answers only to the app owner's Studio token (401 for app visitors and webhooks). Recipes: anonymous checkout step or inbound webhook/IPN -> require_auth=false; signed-in members -> require_auth=true + allowed_roles (e.g. ['authenticated'] or ['admin','staff']); webhook with a shared secret -> require_secret=true + secret_name (an app secret) that the caller sends in secret_header. allowed_hosts fences the function's outbound network to those hosts plus the platform backend; omit it for open egress.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"function":{"type":"string","description":"Function name, e.g. takbull_create (file functions/takbull_create.js)"},"require_auth":{"type":"boolean","default":true,"description":"false = anonymous visitors and external callers may invoke"},"allowed_roles":{"type":"array","items":{"type":"string"},"default":[],"description":"App roles allowed when require_auth is true; 'authenticated' = any signed-in app member"},"require_secret":{"type":"boolean","default":false,"description":"Caller must send a shared secret header (webhooks)"},"secret_name":{"type":"string","default":"","description":"Name of the app secret holding the shared value (set_secret)"},"secret_header":{"type":"string","default":"x-fse2-secret","description":"Header the caller sends the shared secret in"},"allowed_hosts":{"type":"array","items":{"type":"string"},"description":"Outbound egress allow-list of host[:port] entries, e.g. ['api.takbull.co.il']. Omit to keep the stored list; pass [] to open egress again"},"sdk_identity":{"type":"string","enum":["caller","app"],"description":"Whose identity the SDK inside the function uses. 'caller' (default): the function reads data as whoever called it, so an anonymous call sees only what anonymous may read. 'app': the SDK acts as the app owner on THIS app's entities (a checkout or payment IPN that must load/update orders whose read policy is owner/admin/staff); the caller still counts as anonymous for rate limits, audit and X-FSe2-Caller-Type. Owner-only. Omit to keep the stored value"}},"required":["app_id","function","require_auth"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/invoke_function":{"post":{"operationId":"invoke_function","summary":"Run a backend function of an owned app exactly like the HTTP route and return its status and JSON","description":"Run a backend function of an owned app exactly like the HTTP route and return its status and JSON. caller='owner' runs as the app owner; caller='anonymous' first evaluates the function policy as a public visitor and returns the 401/403 decision without running when access would be denied. Use it to verify a function (secrets, outbound calls, policy) before wiring it into the app.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"function":{"type":"string","description":"Function name, e.g. probe"},"params":{"type":"object","description":"JSON body passed to the function","default":{}},"caller":{"type":"string","enum":["owner","anonymous"],"default":"owner"},"headers":{"type":"object","description":"Optional extra request headers to simulate, e.g. a webhook secret header","default":{}}},"required":["app_id","function"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/create_platform_request":{"post":{"operationId":"create_platform_request","summary":"Open a request to the Fine Structure platform team: a bug, a feature request or a question about the platform itself ...","description":"Open a request to the Fine Structure platform team: a bug, a feature request or a question about the platform itself (not about the user's app). Use it when something in the platform blocks you instead of working around it. Give a reproduction the team can run (invoke_function / curl / the exact tool call and result), what you expected, and how the team will know it is closed. Credential-looking values are redacted. Returns request_id and a Studio URL; the team's replies, status changes and deployments come back through get_platform_request / list_platform_requests. Limits: 20 per account per day, 32 KB.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["bug","feature","question"]},"title":{"type":"string","description":"One line, what is wrong or missing"},"body":{"type":"string","description":"Free text, markdown allowed: context, impact, what you tried"},"app_id":{"type":"string","description":"Optional: the app where it showed up"},"severity":{"type":"string","enum":["blocker","high","normal","low"],"default":"normal"},"reproduction":{"type":"string","description":"Steps, invoke_function calls or curl commands that reproduce it"},"expected":{"type":"string","description":"What should have happened"},"acceptance":{"type":"string","description":"How the team will know it is closed"},"attachments":{"type":"array","items":{"type":"string"},"description":"Optional app file paths or log ids","default":[]}},"required":["type","title","body"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/get_platform_request":{"post":{"operationId":"get_platform_request","summary":"One platform request with its full history: team replies, status changes (open | triaged | in_progress | needs_info |...","description":"One platform request with its full history: team replies, status changes (open | triaged | in_progress | needs_info | deployed | wont_fix) and what was deployed (commit, time). Pass since=<ISO timestamp> to get only the events after it.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"since":{"type":"string","description":"Optional ISO timestamp: only events after it"}},"required":["request_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/list_platform_requests":{"post":{"operationId":"list_platform_requests","summary":"Your account's platform requests, newest activity first","description":"Your account's platform requests, newest activity first. Call it at the start of a session with since=<the updated_date you last saw> to learn what changed: replies, needs_info questions to answer, deployments with their commit. Filters: app_id, status.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"Optional app filter"},"status":{"type":"string","enum":["open","triaged","in_progress","needs_info","deployed","wont_fix"]},"since":{"type":"string","description":"Optional ISO timestamp: only requests touched after it, each with changes_since"},"limit":{"type":"integer","default":100},"scope":{"type":"string","enum":["mine","all"],"default":"mine","description":"'all' = every account (platform team only)"}}}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/reply_platform_request":{"post":{"operationId":"reply_platform_request","summary":"Add a reply or a finding to one of your platform requests without opening a new one, e.g","description":"Add a reply or a finding to one of your platform requests without opening a new one, e.g. to answer a needs_info question (that reopens it).","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"body":{"type":"string","description":"The answer or finding (markdown allowed, credentials are redacted)"},"as_team":{"type":"boolean","default":false,"description":"Platform team only: reply as the team (mails the requester)"}},"required":["request_id","body"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/update_platform_request":{"post":{"operationId":"update_platform_request","summary":"Platform team only: set the status of a request (open | triaged | in_progress | needs_info | deployed | wont_fix), at...","description":"Platform team only: set the status of a request (open | triaged | in_progress | needs_info | deployed | wont_fix), attach the deployed commit and/or reply. deployed and needs_info mail the requester.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"status":{"type":"string","enum":["open","triaged","in_progress","needs_info","deployed","wont_fix"]},"reply":{"type":"string"},"deployed_commit":{"type":"string","description":"Commit hash or tag that shipped it"}},"required":["request_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/set_entity_policy":{"post":{"operationId":"set_entity_policy","summary":"Replace server-side entity access policy","description":"Replace server-side entity access policy. Optional action rules override read/write roles and can allow public create without public read, update, or delete. Omitting rules replaces any existing action rules with read/write role behavior.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"entity":{"type":"string","description":"Entity name, e.g. Booking"},"read":{"type":"array","items":{"type":"string"},"description":"Roles allowed to read when rules are omitted"},"write":{"type":"array","items":{"type":"string"},"description":"Roles allowed to write when rules are omitted"},"rules":{"type":"object","description":"Nonempty unconditional action/role rules. No matching rule denies access. Include owner/admin actions explicitly. Record conditions are not supported by this MCP input.","additionalProperties":false,"properties":{"version":{"type":"integer","enum":[1]},"rules":{"type":"array","minItems":1,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"actions":{"type":"array","minItems":1,"items":{"type":"string","enum":["create","read","update","delete","write"]}},"subject":{"type":"object","additionalProperties":false,"properties":{"roles":{"type":"array","minItems":1,"items":{"type":"string"}}},"required":["roles"]}},"required":["actions","subject"]}}},"required":["rules"]}},"required":["app_id","entity","read","write"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/list_app_members":{"post":{"operationId":"list_app_members","summary":"List generated-app runtime users/members for an app","description":"List generated-app runtime users/members for an app. This is separate from Studio project collaborators.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"}},"required":["app_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/invite_app_member":{"post":{"operationId":"invite_app_member","summary":"Provision a generated-app runtime member with a role","description":"Provision a generated-app runtime member with a role. This does not create a Studio collaborator, and the owner role cannot be assigned. password is required: ask the account owner which password the member should get. This tool never generates one, because a generated password would come back in the result and that is a live credential in the conversation transcript.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"email":{"type":"string","description":"Member email"},"role":{"type":"string","description":"App role, e.g. admin/staff/customer"},"full_name":{"type":"string","default":""},"password":{"type":"string","description":"The password this member signs in with, chosen by the account owner. Required, and never echoed back in the result."}},"required":["app_id","email","role","password"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/update_app_member_role":{"post":{"operationId":"update_app_member_role","summary":"Update a generated-app runtime member role","description":"Update a generated-app runtime member role. This cannot assign owner and cannot change the Fine Structure account owner.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"user_id":{"type":"string","description":"Generated app user id"},"role":{"type":"string","description":"New role"}},"required":["app_id","user_id","role"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/remove_app_member":{"post":{"operationId":"remove_app_member","summary":"Remove a generated-app runtime member","description":"Remove a generated-app runtime member.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"user_id":{"type":"string","description":"Generated app user id"}},"required":["app_id","user_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/get_app_security_audit":{"post":{"operationId":"get_app_security_audit","summary":"Read recent server-side security audit events for an app","description":"Read recent server-side security audit events for an app.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"limit":{"type":"integer","default":100}},"required":["app_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/compare_saved_versions":{"post":{"operationId":"compare_saved_versions","summary":"Compare two Saved Versions and return per-file additions, removals, modifications, and compact diffs","description":"Compare two Saved Versions and return per-file additions, removals, modifications, and compact diffs.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"base_snapshot_id":{"type":"string","description":"Older/base snapshot ID"},"target_snapshot_id":{"type":"string","description":"Newer/target snapshot ID"},"max_diff_chars":{"type":"integer","default":12000}},"required":["app_id","base_snapshot_id","target_snapshot_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/compare_current_to_version":{"post":{"operationId":"compare_current_to_version","summary":"Compare the current app files to a Saved Version and return compact per-file diffs","description":"Compare the current app files to a Saved Version and return compact per-file diffs.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"snapshot_id":{"type":"string","description":"Saved Version snapshot ID"},"max_diff_chars":{"type":"integer","default":12000}},"required":["app_id","snapshot_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/restore_file_from_version":{"post":{"operationId":"restore_file_from_version","summary":"Restore one file from a Saved Version instead of restoring the entire app","description":"Restore one file from a Saved Version instead of restoring the entire app. Creates a Saved Version before changing the file. Paths follow the Fine Structure app file API, documented at https://finestructure.ai/api/mcp/docs.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"snapshot_id":{"type":"string","description":"Saved Version snapshot ID"},"path":{"type":"string","description":"Virtual file path to restore"},"confirm":{"type":"boolean","default":false}},"required":["app_id","snapshot_id","path","confirm"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/create_entity_schema":{"post":{"operationId":"create_entity_schema","summary":"Create an entity schema file in entities/<Entity>.json","description":"Create an entity schema file in entities/<Entity>.json. Creates a Saved Version before writing.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"entity":{"type":"string","description":"Entity name"},"schema":{"type":"object","description":"JSON schema object"},"relationships":{"type":"array","items":{"type":"object"},"default":[]},"indexes":{"type":"array","items":{"type":"object"},"default":[]},"metadata":{"type":"object","default":{}},"overwrite":{"type":"boolean","default":false}},"required":["app_id","entity","schema"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/update_entity_schema":{"post":{"operationId":"update_entity_schema","summary":"Replace or shallow-merge an existing entity schema file","description":"Replace or shallow-merge an existing entity schema file. Creates a Saved Version before writing.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"entity":{"type":"string","description":"Entity name"},"schema":{"type":"object","description":"Schema fields to set or merge"},"relationships":{"type":"array","items":{"type":"object"},"default":[]},"indexes":{"type":"array","items":{"type":"object"},"default":[]},"metadata":{"type":"object","default":{}},"merge":{"type":"boolean","default":true}},"required":["app_id","entity","schema"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/validate_entity_relationships":{"post":{"operationId":"validate_entity_relationships","summary":"Validate entity relationship metadata and *_id references against existing entity schemas","description":"Validate entity relationship metadata and *_id references against existing entity schemas.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"}},"required":["app_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/update_entity_metadata":{"post":{"operationId":"update_entity_metadata","summary":"Set relationship/index metadata on an entity schema","description":"Set relationship/index metadata on an entity schema. This stores metadata in the schema file; DB index creation is automatic where supported by the platform.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"entity":{"type":"string","description":"Entity name"},"relationships":{"type":"array","items":{"type":"object"},"default":[]},"indexes":{"type":"array","items":{"type":"object"},"default":[]},"metadata":{"type":"object","default":{}}},"required":["app_id","entity"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/list_secret_keys":{"post":{"operationId":"list_secret_keys","summary":"List secret key names for an app","description":"List secret key names for an app. Secret values are never returned.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"}},"required":["app_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/set_secret":{"post":{"operationId":"set_secret","summary":"Create or update one encrypted app secret","description":"Create or update one encrypted app secret. The secret value is never returned.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"key":{"type":"string","description":"Secret key name"},"value":{"type":"string","description":"Secret value to encrypt and store"}},"required":["app_id","key","value"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/delete_secret":{"post":{"operationId":"delete_secret","summary":"Delete one app secret by key","description":"Delete one app secret by key.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"key":{"type":"string","description":"Secret key name"}},"required":["app_id","key"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/list_integrations":{"post":{"operationId":"list_integrations","summary":"List supported integrations and safe connected integration metadata for an app","description":"List supported integrations and safe connected integration metadata for an app. Tokens/secrets are never returned.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"}},"required":["app_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/configure_integration":{"post":{"operationId":"configure_integration","summary":"Store safe non-secret integration metadata for an app","description":"Store safe non-secret integration metadata for an app. Use set_secret for API keys/tokens.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"provider":{"type":"string","description":"Integration provider ID"},"config":{"type":"object","description":"Safe metadata only, such as workspace/team/name/email"},"is_active":{"type":"boolean","description":"Set false to disconnect this integration metadata","default":true}},"required":["app_id","provider","config"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/list_ab_tests":{"post":{"operationId":"list_ab_tests","summary":"List the platform A/B tests configured for an app","description":"List the platform A/B tests configured for an app.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"}},"required":["app_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/create_ab_test":{"post":{"operationId":"create_ab_test","summary":"Create a native Fine Structure A/B test between existing app pages","description":"Create a native Fine Structure A/B test between existing app pages. Use update_app first if a variant page still needs to be generated. Creates a Saved Version before the change.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"name":{"type":"string","description":"Experiment name"},"page_name":{"type":"string","description":"Base route page that triggers the experiment"},"variants":{"type":"array","items":{"type":"object","properties":{"page_name":{"type":"string","description":"Existing app page name or path"},"traffic_percent":{"type":"integer","description":"Traffic percentage for this variant"}},"required":["page_name","traffic_percent"]},"description":"At least two variants. Traffic must total 100."},"goal_event_type":{"type":"string","description":"Optional conversion goal type: entity_create, any, form_submit"},"goal_event_filter":{"type":"object","description":"Optional goal filter, for example {'entity_name': 'Lead'}"},"is_active":{"type":"boolean","description":"Whether to activate the test immediately","default":true}},"required":["app_id","name","page_name","variants"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/update_ab_test":{"post":{"operationId":"update_ab_test","summary":"Update a native A/B test, including active state, variants, traffic, and conversion goal","description":"Update a native A/B test, including active state, variants, traffic, and conversion goal. Creates a Saved Version before the change.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"test_id":{"type":"string","description":"A/B test ID"},"name":{"type":"string","description":"Optional new name"},"page_name":{"type":"string","description":"Optional new base route page"},"variants":{"type":"array","items":{"type":"object"},"description":"Optional replacement variants. Traffic must total 100."},"is_active":{"type":"boolean","description":"Optional active state"},"goal_event_type":{"type":"string","description":"Optional conversion goal type"},"goal_event_filter":{"type":"object","description":"Optional conversion goal filter"}},"required":["app_id","test_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/delete_ab_test":{"post":{"operationId":"delete_ab_test","summary":"Delete a native A/B test from an app","description":"Delete a native A/B test from an app. Creates a Saved Version before the change.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"test_id":{"type":"string","description":"A/B test ID"}},"required":["app_id","test_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/get_ab_test_stats":{"post":{"operationId":"get_ab_test_stats","summary":"Get views, unique visitors, conversions, and conversion rates for an A/B test","description":"Get views, unique visitors, conversions, and conversion rates for an A/B test.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"test_id":{"type":"string","description":"A/B test ID"}},"required":["app_id","test_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/email_marketing_status":{"post":{"operationId":"email_marketing_status","summary":"Admin only","description":"Admin only. Inspect the isolated Email Marketing module: enabled state, sender settings, templates, sequences, variable triggers, and recent campaign status.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"include_logs":{"type":"boolean","description":"Include recent delivery logs","default":false}}}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/email_marketing_configure_sender":{"post":{"operationId":"email_marketing_configure_sender","summary":"Admin only","description":"Admin only. Configure global Email Marketing sender details and module enabled state. Unsubscribe footer remains mandatory.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"is_enabled":{"type":"boolean","description":"Enable or disable the module at settings level"},"sender_name":{"type":"string","description":"Display sender name"},"sender_email":{"type":"string","description":"Sender email address used by the email provider"},"reply_to":{"type":"string","description":"Reply-To email address"},"organization_name":{"type":"string","description":"Organization name used in unsubscribe footer"},"postal_address":{"type":"string","description":"Optional postal/contact address for compliance"},"default_timezone":{"type":"string","description":"Default timezone for scheduling"}}}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/email_marketing_update_template":{"post":{"operationId":"email_marketing_update_template","summary":"Admin only","description":"Admin only. Update an automatic Email Marketing template, such as user_joined welcome email. The unsubscribe block is still appended by the server.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"template_id":{"type":"string","description":"Template/event id, e.g. user_joined"},"enabled":{"type":"boolean","description":"Whether this automatic template is active"},"subject":{"type":"string","description":"Email subject with {{variables}}"},"body_html":{"type":"string","description":"HTML body with {{variables}}"}},"required":["template_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/email_marketing_create_broadcast":{"post":{"operationId":"email_marketing_create_broadcast","summary":"Admin only","description":"Admin only. Create a filtered broadcast campaign, optionally scheduled or sent now.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Internal campaign name"},"subject":{"type":"string","description":"Email subject"},"body_html":{"type":"string","description":"HTML body. Unsubscribe is appended automatically."},"filters":{"type":"object","description":"Recipient filters: plans, roles, active_status, email_verified, min_apps, max_apps, has_published_app, search"},"scheduled_at":{"type":"string","description":"Optional ISO datetime. If no timezone is included, timezone is used."},"timezone":{"type":"string","description":"Timezone for naive scheduled_at","default":"UTC"},"send_now":{"type":"boolean","description":"Send immediately after creating the campaign","default":false}},"required":["subject","body_html"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/email_marketing_create_sequence":{"post":{"operationId":"email_marketing_create_sequence","summary":"Admin only","description":"Admin only. Create a scheduled email sequence using fixed dates or day offsets. Each generated email keeps mandatory unsubscribe.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Sequence name"},"schedule_mode":{"type":"string","enum":["fixed_dates","day_offsets"],"description":"fixed_dates uses each step.scheduled_at; day_offsets uses start_at + step day offsets"},"filters":{"type":"object","description":"Recipient filters"},"start_at":{"type":"string","description":"ISO datetime for day_offsets mode"},"timezone":{"type":"string","default":"UTC"},"steps":{"type":"array","items":{"type":"object"},"description":"Steps with subject, body_html, and either scheduled_at (fixed_dates) or day_offset/gap_days (day_offsets)."}},"required":["name","schedule_mode","steps"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/email_marketing_create_variable_trigger":{"post":{"operationId":"email_marketing_create_variable_trigger","summary":"Admin only","description":"Admin only. Create an email rule that sends when a named variable changes from one value to another. Empty from_value/to_value acts as wildcard.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Trigger name"},"enabled":{"type":"boolean","default":true},"variable_name":{"type":"string","description":"Variable name, e.g. plan"},"from_value":{"type":"string","description":"Previous value or empty wildcard"},"to_value":{"type":"string","description":"New value or empty wildcard"},"subject":{"type":"string","description":"Email subject"},"body_html":{"type":"string","description":"HTML body. Unsubscribe is appended automatically."},"filters":{"type":"object","description":"Optional recipient filters"}},"required":["variable_name","subject","body_html"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/email_marketing_trigger_variable":{"post":{"operationId":"email_marketing_trigger_variable","summary":"Admin only","description":"Admin only. Manually fire variable-transition email rules for one user. Useful for MCP/agent workflows and tests.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":"string","description":"Platform user id"},"variable_name":{"type":"string","description":"Variable name"},"from_value":{"type":"string","description":"Previous value"},"to_value":{"type":"string","description":"New value"},"context":{"type":"object","description":"Extra template variables"}},"required":["user_id","variable_name"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/email_marketing_app_status":{"post":{"operationId":"email_marketing_app_status","summary":"Inspect app-scoped Email Marketing for one generated app: settings, contacts, campaigns, event triggers, and recent e...","description":"Inspect app-scoped Email Marketing for one generated app: settings, contacts, campaigns, event triggers, and recent events.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"include_logs":{"type":"boolean","default":false}},"required":["app_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/email_marketing_app_configure":{"post":{"operationId":"email_marketing_app_configure","summary":"Configure isolated Email Marketing settings for a generated app","description":"Configure isolated Email Marketing settings for a generated app. Can be used by Studio/chat agents.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"is_enabled":{"type":"boolean"},"default_contact_entity":{"type":"string","description":"Entity to sync as contacts, e.g. Customer or Lead"},"default_email_field":{"type":"string","description":"Field containing contact email"},"default_name_field":{"type":"string","description":"Field containing contact name"},"sender_name":{"type":"string"},"sender_email":{"type":"string"},"reply_to":{"type":"string"}},"required":["app_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/email_marketing_app_sync_contacts":{"post":{"operationId":"email_marketing_app_sync_contacts","summary":"Sync an app entity table into app-scoped Email Marketing contacts","description":"Sync an app entity table into app-scoped Email Marketing contacts. Records without a valid email are skipped.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"entity_name":{"type":"string","description":"Entity name, e.g. Customer or Lead"},"email_field":{"type":"string","default":"email"},"name_field":{"type":"string"},"limit":{"type":"integer","default":1000}},"required":["app_id","entity_name"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/email_marketing_app_create_broadcast":{"post":{"operationId":"email_marketing_app_create_broadcast","summary":"Create an app-scoped broadcast to contacts synced from that generated app, optionally scheduled or sent now","description":"Create an app-scoped broadcast to contacts synced from that generated app, optionally scheduled or sent now.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"name":{"type":"string"},"subject":{"type":"string"},"body_html":{"type":"string"},"filters":{"type":"object","description":"App contact filters such as source_entity, search, tags, field_equals"},"scheduled_at":{"type":"string"},"timezone":{"type":"string","default":"UTC"},"send_now":{"type":"boolean","default":false}},"required":["app_id","subject","body_html"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/email_marketing_app_create_event_trigger":{"post":{"operationId":"email_marketing_app_create_event_trigger","summary":"Create an app-scoped email rule that sends when an app event is recorded, for example entity_created or Customer.created","description":"Create an app-scoped email rule that sends when an app event is recorded, for example entity_created or Customer.created.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"name":{"type":"string"},"enabled":{"type":"boolean","default":true},"event_name":{"type":"string","description":"Event name, e.g. entity_created, Customer.created, order_paid"},"entity_name":{"type":"string","description":"Optional entity filter"},"subject":{"type":"string"},"body_html":{"type":"string"},"filters":{"type":"object","description":"Optional app contact filters"}},"required":["app_id","event_name","subject","body_html"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/email_marketing_app_record_event":{"post":{"operationId":"email_marketing_app_record_event","summary":"Record an app event and send matching app-scoped Email Marketing triggers","description":"Record an app event and send matching app-scoped Email Marketing triggers.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"event_name":{"type":"string"},"email":{"type":"string","description":"Contact email if no contact_id is known"},"contact_id":{"type":"string"},"entity_name":{"type":"string"},"record_id":{"type":"string"},"record":{"type":"object","description":"Entity record fields for template variables and contact extraction"},"properties":{"type":"object","description":"Extra event properties"}},"required":["app_id","event_name"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/email_marketing_app_create_workflow":{"post":{"operationId":"email_marketing_app_create_workflow","summary":"Create an app-scoped automation workflow with email, wait, condition, split, and goal steps","description":"Create an app-scoped automation workflow with email, wait, condition, split, and goal steps.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"name":{"type":"string"},"enabled":{"type":"boolean","default":true},"trigger_event_name":{"type":"string","description":"Event that enrolls a contact, e.g. Customer.created"},"trigger_entity_name":{"type":"string","description":"Optional entity filter"},"steps":{"type":"array","description":"Ordered workflow steps. Supported type values: email, wait, condition, split, goal.","items":{"type":"object"}},"definition":{"type":"object","description":"Optional full workflow definition; steps can also be supplied here."}},"required":["app_id","trigger_event_name"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/email_marketing_app_create_sequence":{"post":{"operationId":"email_marketing_app_create_sequence","summary":"Create an app-scoped email sequence using fixed dates or day offsets between emails","description":"Create an app-scoped email sequence using fixed dates or day offsets between emails.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"name":{"type":"string"},"schedule_mode":{"type":"string","enum":["fixed_dates","day_offsets"],"default":"day_offsets"},"start_at":{"type":"string","description":"Sequence start date/time for day_offsets mode"},"timezone":{"type":"string","default":"UTC"},"filters":{"type":"object","description":"App contact filters"},"steps":{"type":"array","description":"Emails in order. Each step supports subject, body_html, scheduled_at, day_offset, or gap_days.","items":{"type":"object"}}},"required":["app_id","steps"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/email_marketing_app_report":{"post":{"operationId":"email_marketing_app_report","summary":"Read app-scoped Email Marketing reporting: delivery counts, open/click rates, and recent tracking events","description":"Read app-scoped Email Marketing reporting: delivery counts, open/click rates, and recent tracking events.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"include_events":{"type":"boolean","default":true},"limit":{"type":"integer","default":50},"segment_limit":{"type":"integer","default":25}},"required":["app_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/email_marketing_app_create_segment":{"post":{"operationId":"email_marketing_app_create_segment","summary":"Create an app-scoped saved audience segment using field, tag, and behavior filters","description":"Create an app-scoped saved audience segment using field, tag, and behavior filters.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"name":{"type":"string"},"filters":{"type":"object","description":"Segment filters. Supports rules with field/operator/value plus opened/clicked/sent behavior fields."},"sample_limit":{"type":"integer","default":10}},"required":["app_id","name","filters"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/email_marketing_app_contact_profile":{"post":{"operationId":"email_marketing_app_contact_profile","summary":"Read a contact profile with email delivery, tracking, app-event, workflow, suppression, and unsubscribe timeline","description":"Read a contact profile with email delivery, tracking, app-event, workflow, suppression, and unsubscribe timeline.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"contact":{"type":"string","description":"Contact id or email address"}},"required":["app_id","contact"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/email_marketing_app_deliverability":{"post":{"operationId":"email_marketing_app_deliverability","summary":"Read provider readiness, bounce/complaint rates, suppression reasons, and recent deliverability risk events","description":"Read provider readiness, bounce/complaint rates, suppression reasons, and recent deliverability risk events.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"}},"required":["app_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/email_marketing_app_process_queue":{"post":{"operationId":"email_marketing_app_process_queue","summary":"Process due app-scoped automation workflow runs and email queue jobs with locks, retries, and suppression checks","description":"Process due app-scoped automation workflow runs and email queue jobs with locks, retries, and suppression checks.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"max_jobs":{"type":"integer","default":50}},"required":["app_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/email_marketing_app_queue_status":{"post":{"operationId":"email_marketing_app_queue_status","summary":"Inspect app-scoped Email Marketing queue jobs and per-status counts","description":"Inspect app-scoped Email Marketing queue jobs and per-status counts.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"limit":{"type":"integer","default":50},"status":{"type":"string","description":"Optional queue status filter"}},"required":["app_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/email_marketing_app_suppress_contact":{"post":{"operationId":"email_marketing_app_suppress_contact","summary":"Suppress an app contact email after a bounce, complaint, manual block, provider block, or unsubscribe","description":"Suppress an app contact email after a bounce, complaint, manual block, provider block, or unsubscribe.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"The app ID"},"email":{"type":"string"},"reason":{"type":"string","default":"manual"},"source":{"type":"string","default":"mcp"},"metadata":{"type":"object"}},"required":["app_id","email"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/list_media_capabilities":{"post":{"operationId":"list_media_capabilities","summary":"Discovery for the media tools: the active image model and remaining image allowance, the video models this account ma...","description":"Discovery for the media tools: the active image model and remaining image allowance, the video models this account may use with their per-second prices and prepaid wallet balance, and every valid slideshow style, template, and collection id. Call this before generate_image / generate_video / generate_slideshow instead of guessing enum values. Spends nothing.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"surfaces":{"type":"array","items":{"type":"string","enum":["image","video","slideshow"]},"description":"Limit the answer to these surfaces. Default: all three."}}}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/generate_image":{"post":{"operationId":"generate_image","summary":"Generate one marketing image (ad creative, thumbnail, hero, social graphic) and return a public URL","description":"Generate one marketing image (ad creative, thumbnail, hero, social graphic) and return a public URL. Free plans burn one of their monthly free images; paid plans spend 1 platform credit. Optionally pass a reference image to keep a person, product, place, or brand consistent.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","description":"What to draw. Up to 4500 chars."},"language":{"type":"string","description":"Language of any text in the image. ISO code such as 'en' or 'he'. Defaults to 'en'."},"reference_image_url":{"type":"string","description":"Public https URL of a reference image, or one of this account's own finestructure.ai uploads."},"reference_image_data_url":{"type":"string","description":"Reference image inline as a data:image/... URL. Prefer reference_image_url for large files."},"reference_image_data_urls":{"type":"array","items":{"type":"string"},"description":"Up to 6 extra reference images as data:image/... URLs."},"notify_by_email":{"type":"boolean","description":"Email the account owner the finished image. Default false so batch runs do not spam.","default":false}},"required":["prompt"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/estimate_video_cost":{"post":{"operationId":"estimate_video_cost","summary":"Price a video render before generating it","description":"Price a video render before generating it. Returns the duration, resolution, and the exact charge in USD against the prepaid video wallet. Spends nothing.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"model":{"type":"string","description":"Model id from list_media_capabilities. Default 'seedance-2'."},"duration":{"type":"integer","description":"Seconds. Snapped to the model's allowed values."},"resolution":{"type":"string","description":"480p, 720p, or 1080p (model dependent)."}}}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/generate_video":{"post":{"operationId":"generate_video","summary":"Generate an AI video from a text prompt","description":"Generate an AI video from a text prompt. Submits the render and returns a job_id immediately - poll get_video_status until it completes. Spends the account's prepaid video-credit wallet (NOT platform credits); pass max_charge_usd to cap how much a single call may spend. Video generation may be invitation-gated.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","description":"The shot to render. Up to 4000 chars."},"model":{"type":"string","description":"Model id from list_media_capabilities. Default 'seedance-2'."},"duration":{"type":"integer","description":"Seconds. Snapped to the model's allowed values."},"resolution":{"type":"string","description":"480p, 720p, or 1080p (model dependent). Default 480p."},"aspect_ratio":{"type":"string","description":"auto, 16:9, 9:16, 1:1, 4:3, 3:4, or 21:9. Default auto."},"image_urls":{"type":"array","items":{"type":"string"},"description":"Up to 9 public https reference images (Seedance models only)."},"max_charge_usd":{"type":"number","description":"Refuse the render if it would charge more than this. Strongly recommended for autonomous agents."}},"required":["prompt"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/get_video_status":{"post":{"operationId":"get_video_status","summary":"Poll one video job by id","description":"Poll one video job by id. Refreshes from the provider while it is still rendering and returns video_url once status is 'completed'. Spends nothing.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","description":"Job id returned by generate_video."}},"required":["job_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/list_video_jobs":{"post":{"operationId":"list_video_jobs","summary":"List this account's own video jobs, newest first","description":"List this account's own video jobs, newest first. Spends nothing.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"integer","description":"How many jobs to return, 1-100. Default 20."}}}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/generate_slideshow":{"post":{"operationId":"generate_slideshow","summary":"Write a TikTok/Instagram-style slideshow: hook, per-slide copy, caption, and hashtags, in any supported language","description":"Write a TikTok/Instagram-style slideshow: hook, per-slide copy, caption, and hashtags, in any supported language. Costs 1 platform credit and returns the script for review. Set render_images=true to start image rendering right away (1 extra credit per slide), then poll get_slideshow until status is 'ready'. Pass slide_images to composite the slides on the account's own photos (Instagram carousel mode) and output_format for 9:16, 4:5, or 1:1 geometry. Call list_media_capabilities for the valid style, template, and collection ids.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"goal":{"type":"string","description":"What the slideshow should achieve or teach."},"language":{"type":"string","description":"ISO code such as 'en' or 'he'. Defaults to 'en'."},"content_style":{"type":"string","description":"Copy archetype, e.g. x_ways, storytelling, countdown_ranking."},"visual_style":{"type":"string","description":"Visual look, e.g. bold_gradient, tiktok_native_photo."},"template":{"type":"string","description":"Built-in template id whose voice spec dominates the output."},"slide_count":{"type":"integer","description":"Fixed number of slides. Omit for the style's natural range."},"narrative_device":{"type":"string","description":"Framing device, e.g. metaphor or famous_quote."},"x_ways_substyle":{"type":"string","description":"How numbered ways are written (x_ways content style only)."},"authentic_mode":{"type":"boolean","description":"Lowercase, unpolished 'real person' voice."},"with_graphics":{"type":"boolean","description":"Rich visuals vs clean text-only slides. Default true."},"enhanced":{"type":"boolean","description":"Use the higher-quality (more expensive) image model."},"text_align":{"type":"string","description":"left, right, or center."},"accent_color":{"type":"string","description":"Hex accent for the chip text style."},"collection":{"type":"string","description":"Saved photo collection id to pull slide photos from."},"output_format":{"type":"string","enum":["tiktok","ig_portrait","ig_square"],"description":"Slide geometry: tiktok 9:16 (default), ig_portrait 4:5 Instagram carousel, ig_square 1:1."},"slide_images":{"type":"array","items":{"type":"string"},"description":"Up to 10 of the account's own photos, in slide order, each a data:image/... URL or public https URL. When present, the slides are composited on these exact photos: one slide per image, no CTA slide appended."},"slide_texts":{"type":"array","items":{"type":"string"},"description":"Per-slide overlay text in slide order, up to 300 chars each. Kept verbatim; leave an entry empty (or omit the array) to have the AI write it."},"cta_url":{"type":"string","description":"Link promoted on the final slide. Omit for pure-value content."},"cta_platforms":{"type":"array","items":{"type":"string","enum":["ios","android","web"]},"description":"What the CTA actually offers."},"sales_bridge":{"type":"boolean","description":"Add pre-sale bridge slides before the offer."},"series_part":{"type":"integer","description":"Part number for a recurring series."},"voice_spec":{"type":"string","description":"A reference voice spec to reproduce exactly."},"render_images":{"type":"boolean","description":"Start rendering images immediately after the script. Default false (review first).","default":false}},"required":["goal"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/render_slideshow_images":{"post":{"operationId":"render_slideshow_images","summary":"Render the images for a slideshow whose script was already written and approved","description":"Render the images for a slideshow whose script was already written and approved. Charges 1 platform credit per slide, runs in the background, and returns immediately - poll get_slideshow until status is 'ready'.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"history_id":{"type":"integer","description":"history_id returned by generate_slideshow."}},"required":["history_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/get_slideshow":{"post":{"operationId":"get_slideshow","summary":"Fetch one slideshow: its script, render status (script_ready, rendering, ready, render_failed), and the image URL of ...","description":"Fetch one slideshow: its script, render status (script_ready, rendering, ready, render_failed), and the image URL of every rendered slide. Spends nothing.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"history_id":{"type":"integer","description":"history_id returned by generate_slideshow."}},"required":["history_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/list_slideshows":{"post":{"operationId":"list_slideshows","summary":"List this account's slideshows, newest first, without slide bodies","description":"List this account's slideshows, newest first, without slide bodies. Spends nothing.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"integer","description":"How many to return, 1-60. Default 20."}}}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/get_creative_capabilities":{"post":{"operationId":"get_creative_capabilities","summary":"Discover the complete Creative Studio workspace, copy, image references, slide editing, gallery, social publishing an...","description":"Discover the complete Creative Studio workspace, copy, image references, slide editing, gallery, social publishing and recurring workflows. Request operation for its native parameter schema or topic=guide. Account-level OAuth or API token with explicit media scopes required.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"operation":{"type":"string","enum":["automations.create","automations.delete","automations.duplicate","automations.feedback_create","automations.feedback_delete","automations.feedback_update","automations.list","automations.readiness","automations.run","automations.runs","automations.update","collections.generate","collections.list","collections.upload","copy.blocks","copy.plan","history.cta_image","history.delete","history.events","history.get","history.list","history.rate","landing.analyze","reference.analyze","references.delete","references.get","references.upload","script.edit","script.save","slides.insert","slides.regenerate","slides.rerender","social.draft","social.publish","social.publish_tiktok","social.status","templates.list","usage","workspace.get","workspace.save"]},"topic":{"type":"string","enum":["operations","guide"]}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/read_creative":{"post":{"operationId":"read_creative","summary":"Read this account's creative workspace, images, gallery, automation runs and publication status","description":"Read this account's creative workspace, images, gallery, automation runs and publication status. No generation or sends. Discover exact parameters with get_creative_capabilities first.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"operation":{"type":"string","enum":["automations.list","automations.readiness","automations.runs","collections.list","history.cta_image","history.events","history.get","history.list","references.get","social.status","templates.list","usage","workspace.get"]},"parameters":{"type":"object"}},"required":["operation"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/configure_creative":{"post":{"operationId":"configure_creative","summary":"Edit private creative work, plan copy, generate collections, revise slides and manage reference images","description":"Edit private creative work, plan copy, generate collections, revise slides and manage reference images. AI operations incur native credits. Does not publish or activate automated publishing. Discover exact parameters with get_creative_capabilities first.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"operation":{"type":"string","enum":["collections.generate","collections.upload","copy.blocks","copy.plan","history.delete","history.rate","landing.analyze","reference.analyze","references.delete","references.upload","script.edit","script.save","slides.insert","slides.regenerate","slides.rerender","workspace.save"]},"parameters":{"type":"object"}},"required":["operation"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/publish_creative":{"post":{"operationId":"publish_creative","summary":"Publish or schedule creative content, send it to a social draft inbox or manage recurring generation/publishing","description":"Publish or schedule creative content, send it to a social draft inbox or manage recurring generation/publishing. Can spend money and contact third parties. Requires explicit media:publish permission and user authorization. Read actual run/provider status afterwards. Discover exact parameters with get_creative_capabilities first.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"operation":{"type":"string","enum":["automations.create","automations.delete","automations.duplicate","automations.feedback_create","automations.feedback_delete","automations.feedback_update","automations.run","automations.update","social.draft","social.publish","social.publish_tiktok"]},"parameters":{"type":"object"}},"required":["operation"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/get_app_metadata":{"post":{"operationId":"get_app_metadata","summary":"Read the saved public HTML-shell identity: name, description, language and image URLs/dimensions","description":"Read the saved public HTML-shell identity: name, description, language and image URLs/dimensions. Same settings as Studio SEO/GEO.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string"}},"required":["app_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/set_app_metadata":{"post":{"operationId":"set_app_metadata","summary":"Update public HTML-shell metadata immediately, without AI, code edits, publishing or Saved Versions","description":"Update public HTML-shell metadata immediately, without AI, code edits, publishing or Saved Versions. Upload social_image/icon as base64 PNG/JPEG/WebP (max 5 MB, 4096px); null clears an image. Language sets HTML lang/dir and OG locale. For per-page cards, write optional seo.json and publish it; dynamic entries may read only explicitly public entity records.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string"},"name":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":4000},"language":{"type":"string","description":"BCP-47 code, e.g. he, ar, en-US"},"social_image":{"anyOf":[{"type":"object","properties":{"base64":{"type":"string"},"content_type":{"type":"string","enum":["image/png","image/jpeg","image/webp"]}},"required":["base64","content_type"],"additionalProperties":false},{"type":"null"}]},"icon":{"anyOf":[{"type":"object","properties":{"base64":{"type":"string"},"content_type":{"type":"string","enum":["image/png","image/jpeg","image/webp"]}},"required":["base64","content_type"],"additionalProperties":false},{"type":"null"}]},"structured_data":{"type":"string","description":"Optional JSON-LD JSON string; empty clears it"}},"required":["app_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/preview_saved_version":{"post":{"operationId":"preview_saved_version","summary":"Prepare an isolated read-only Saved Version preview, if enabled by the deployment","description":"Prepare an isolated read-only Saved Version preview, if enabled by the deployment. Returns compiled files for an offline sandbox, never restores files or reads live records. Never execute the returned program with host credentials. Requires app access and versions:read.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","minLength":1},"snapshot_id":{"type":"string","minLength":1}},"required":["app_id","snapshot_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/configure_email_domain_dns":{"post":{"operationId":"configure_email_domain_dns","summary":"Configure sending DNS for an already-owned managed email domain on an owned app","description":"Configure sending DNS for an already-owned managed email domain on an owned app. Uses the existing provider onboarding gates. Does not buy a domain, expand sending limits or bypass DNS ownership checks. Changes public DNS; confirm the selected app and domain first.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","minLength":1},"domain":{"type":"string","minLength":1,"maxLength":253}},"required":["app_id","domain"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/set_agent_owner_relay":{"post":{"operationId":"set_agent_owner_relay","summary":"Set the owner's consent for one owned agent to relay reports from another owned agent (or all sources with '*')","description":"Set the owner's consent for one owned agent to relay reports from another owned agent (or all sources with '*'). Uses the same preference as the agent screen. Does not send a message or grant access to customer conversations.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"receiving_agent_id":{"type":"string","minLength":1},"enabled":{"type":"boolean"},"source_agent_id":{"type":"string","minLength":1,"default":"*"}},"required":["receiving_agent_id","enabled"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/create_agent":{"post":{"operationId":"create_agent","summary":"Create an autonomous AI agent on the user's Fine Structure account: a standing worker, not a chat session","description":"Create an autonomous AI agent on the user's Fine Structure account: a standing worker, not a chat session. It gets the platform's default safe tool policy and its own email address, it can read and write the app database, and once the owner phone is verified (see get_agent_whatsapp) it can message its owner on WhatsApp and by email through the platform system channels. Pair it with schedule_agent_task for recurring work such as following up new leads on WhatsApp each morning, watching an app for runtime errors, or sending a weekly summary. Messaging anyone other than the verified owner requires a channel the owner connects in the Fine Structure Studio.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Agent display name (e.g. 'Lead Follow-up'). Auto-derived from role when omitted."},"role":{"type":"string","description":"Short role label (e.g. 'sales assistant')"},"description":{"type":"string","description":"What this agent is responsible for, one or two sentences"},"persona":{"type":"string","description":"Optional working style and tone instructions for the agent"},"app_id":{"type":"string","description":"Optional app to attach the agent to; account-level when omitted"}},"required":["role","description"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/list_agents":{"post":{"operationId":"list_agents","summary":"List the AI agents on the user's account with id, name, role, status and FineMail address","description":"List the AI agents on the user's account with id, name, role, status and FineMail address.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string","description":"Optional filter by attached app"}}}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/schedule_agent_task":{"post":{"operationId":"schedule_agent_task","summary":"Create a scheduled task for one of the user's agents","description":"Create a scheduled task for one of the user's agents. Supported schedule types: once (run_at ISO local time + timezone), interval (interval_minutes 5-1440), hourly, daily (time HH:MM + timezone), weekly (time + timezone + days_of_week 0=Sunday..6), cron (5-field expression + timezone), manual (only runs on demand). Returns the normalized schedule and the computed next_run_at so you can read the fire time back to the user in their timezone.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"agent_id":{"type":"string","description":"The agent id (from create_agent or list_agents)"},"title":{"type":"string","description":"Short task title"},"instructions":{"type":"string","description":"What the agent should do on each run, written as instructions to the agent"},"schedule":{"type":"object","description":"Schedule object, e.g. {\"type\":\"daily\",\"time\":\"08:30\",\"timezone\":\"Asia/Jerusalem\"} or {\"type\":\"weekly\",\"time\":\"09:00\",\"timezone\":\"Asia/Jerusalem\",\"days_of_week\":[0]} or {\"type\":\"once\",\"run_at\":\"2026-08-20T09:00\",\"timezone\":\"Asia/Jerusalem\"}"},"max_runs":{"type":"integer","description":"Optional cap on total runs (0 = unlimited)","default":0},"activate":{"type":"boolean","description":"Start the schedule immediately (true) or save as draft (false)","default":true}},"required":["agent_id","title","instructions","schedule"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/list_agent_tasks":{"post":{"operationId":"list_agent_tasks","summary":"List scheduled tasks for one agent (or the whole account), including schedule, status and next_run_at","description":"List scheduled tasks for one agent (or the whole account), including schedule, status and next_run_at.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"agent_id":{"type":"string","description":"Optional agent id filter"},"status":{"type":"string","description":"Optional status filter: draft, active, paused, archived"},"limit":{"type":"integer","description":"Max tasks to return (1-100)","default":50}}}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/get_agent_whatsapp":{"post":{"operationId":"get_agent_whatsapp","summary":"Read the WhatsApp state of the connected account: whether the owner's phone is verified, which platform numbers they ...","description":"Read the WhatsApp state of the connected account: whether the owner's phone is verified, which platform numbers they can connect, and which conversations already route to which agent. Call this first whenever the user asks to talk to an agent on WhatsApp, and repeat its next_step to them.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"agent_id":{"type":"string","description":"Optional: report only this agent's WhatsApp state."}}}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/start_owner_phone_verification":{"post":{"operationId":"start_owner_phone_verification","summary":"Send a 6-digit code over WhatsApp to the ACCOUNT OWNER's own phone","description":"Send a 6-digit code over WhatsApp to the ACCOUNT OWNER's own phone. This is the one-time ownership proof required before a platform number can be connected, and it also unlocks agents messaging the owner. Ask the user for their own WhatsApp number first and send only to that. No WhatsApp Business account is involved.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phone":{"type":"string","description":"The owner's own WhatsApp number, ideally in E.164 form such as +972501234567."},"region":{"type":"string","description":"Optional ISO region hint (for example IL, US) used when the number has no country code."}},"required":["phone"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/confirm_owner_phone_verification":{"post":{"operationId":"confirm_owner_phone_verification","summary":"Confirm the 6-digit code the owner received on WhatsApp from start_owner_phone_verification","description":"Confirm the 6-digit code the owner received on WhatsApp from start_owner_phone_verification. On success the owner is verified: agents can message them, and platform numbers become connectable.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phone":{"type":"string","description":"The same phone number the code was sent to."},"code":{"type":"string","description":"The 6-digit code from the WhatsApp message."},"region":{"type":"string","description":"Optional ISO region hint, matching the one used when sending."}},"required":["phone","code"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/attach_agent_whatsapp":{"post":{"operationId":"attach_agent_whatsapp","summary":"Connect a platform WhatsApp number to one of the account's agents, so the owner can message that number and reach tha...","description":"Connect a platform WhatsApp number to one of the account's agents, so the owner can message that number and reach that agent. Requires the owner to be verified first. Take phone_number_id from get_agent_whatsapp. A number already used by another account is still valid to connect: it answers only this owner's verified phone.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"agent_id":{"type":"string","description":"The agent that should answer on this number."},"phone_number_id":{"type":"string","description":"phone_number_id from get_agent_whatsapp claimable_numbers."}},"required":["agent_id","phone_number_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/detach_agent_whatsapp":{"post":{"operationId":"detach_agent_whatsapp","summary":"Disconnect the owner's WhatsApp route from a platform number","description":"Disconnect the owner's WhatsApp route from a platform number. Removes only this account's route; other accounts sharing the number keep theirs.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phone_number_id":{"type":"string","description":"The number to disconnect, from get_agent_whatsapp."}},"required":["phone_number_id"]}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/list_agent_conversations":{"post":{"operationId":"list_agent_conversations","summary":"List recent visible conversations belonging to one of your agents","description":"List recent visible conversations belonging to one of your agents. Use get_agent_conversation to read replies and results.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"agent_id":{"type":"string","minLength":1,"description":"Owned agent ID from list_agents."},"limit":{"type":"integer","minimum":1,"maximum":100,"default":50}},"required":["agent_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/send_agent_message":{"post":{"operationId":"send_agent_message","summary":"Talk to an existing agent or assign it work using its normal tools, memory, permissions and team","description":"Talk to an existing agent or assign it work using its normal tools, memory, permissions and team. Omit conversation_id to start a new owner conversation; supply it to continue one. Returns acceptance and a durable task_id immediately, NOT a completed answer. Poll get_agent_task and read get_agent_conversation for the actual response. Work continues after MCP disconnects. A follow-up in a busy conversation uses the normal queue. Customer conversations are readable but cannot be impersonated by this tool.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"agent_id":{"type":"string","minLength":1,"description":"Owned agent ID from list_agents."},"message":{"type":"string","minLength":1},"conversation_id":{"type":"string","minLength":1,"description":"Conversation ID returned by these tools."}},"required":["agent_id","message"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/get_agent_conversation":{"post":{"operationId":"get_agent_conversation","summary":"Read visible messages, answers and result links in an owned agent's conversation","description":"Read visible messages, answers and result links in an owned agent's conversation. Returns the newest page in chronological order. For older history, pass next_before_id as before_id. For new replies, omit before_id.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"agent_id":{"type":"string","minLength":1,"description":"Owned agent ID from list_agents."},"conversation_id":{"type":"string","minLength":1,"description":"Conversation ID returned by these tools."},"limit":{"type":"integer","minimum":1,"maximum":100,"default":50},"before_id":{"type":"string"}},"required":["agent_id","conversation_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/get_agent_task":{"post":{"operationId":"get_agent_task","summary":"Check a durable task returned by send_agent_message or list_agent_tasks","description":"Check a durable task returned by send_agent_message or list_agent_tasks. Includes the latest execution status and pending approvals, including before a run starts. Task scheduling state is separate from run outcome. Read the conversation for the actual answer; accepted/queued is not completed. Approvals must still be decided by the owner in Fine Structure.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"agent_id":{"type":"string","minLength":1,"description":"Owned agent ID from list_agents."},"task_id":{"type":"string","minLength":1}},"required":["agent_id","task_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/get_marketing_capabilities":{"post":{"operationId":"get_marketing_capabilities","summary":"Discover the complete Fine Structure /audiences marketing engine: contacts, segments, email and WhatsApp, templates, ...","description":"Discover the complete Fine Structure /audiences marketing engine: contacts, segments, email and WhatsApp, templates, campaigns, schedules, multi-step flows, inbox, event connections, automations, analytics and settings. Call with operation to get its exact inputSchema before executing it; topic='guide' explains graph and event contracts. Account token required; legacy email scopes do not grant this engine.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"operation":{"type":"string","enum":["activity.list","agents.create_reply","analytics","analytics.explore","assistant.approvals","assistant.decide","assistant.ensure","automations.create","automations.list","automations.update","campaigns.email","campaigns.get","campaigns.list","campaigns.message","campaigns.recipients","campaigns.run","campaigns.schedule","campaigns.scheduled","campaigns.sms","campaigns.whatsapp","contacts.export","contacts.get","contacts.history","contacts.import_file","contacts.import_text","contacts.list","contacts.preview","contacts.query","contacts.tags","contacts.upsert","dashboard","data.contact","data.get","data.history","data.preview","data.restore","data.save","drafts.get","drafts.list","drafts.save","email.confirmation","email.domain.activate","email.experiment","email.gmail.activate","email.gmail.connect","email.gmail.connections","email.policy.get","email.policy.save","email.preview","email.senders","email.templates.delete","email.templates.list","email.templates.save","email.test","events.configure","events.create","events.history","events.install_app","events.preview","events.retry","events.revisions","events.sources","flows.approve","flows.archive","flows.control","flows.create","flows.draft","flows.get","flows.launch","flows.list","flows.update","flows.validate","folders.archive","folders.create","folders.list","folders.move_item","folders.rename","inbox.capabilities","inbox.conversations","inbox.flow","inbox.media","inbox.messages","inbox.reply","library.list","lists.create","lists.delete","lists.from_filters","lists.list","notifications.queue","notifications.status","permissions.history","permissions.list","reply_rules.delete","reply_rules.list","reply_rules.save","reports.get","reports.update","settings.get","settings.update","sms.connections","sms.senders","views.get","views.save","whatsapp.account_profile","whatsapp.accounts","whatsapp.bind_agent","whatsapp.official.create","whatsapp.official.delete","whatsapp.official.duplicate","whatsapp.official.edit","whatsapp.refresh_names","whatsapp.senders","whatsapp.templates.create","whatsapp.templates.delete","whatsapp.templates.duplicate","whatsapp.templates.list","whatsapp.templates.preview","whatsapp.templates.submit","whatsapp.templates.update","whatsapp.test"]},"topic":{"type":"string","enum":["operations","guide"],"default":"operations"}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/read_marketing":{"post":{"operationId":"read_marketing","summary":"Read, query, preview, validate or export owned marketing data","description":"Read, query, preview, validate or export owned marketing data. Never sends a message. Uses the same engine as /audiences. Call get_marketing_capabilities(operation=...) for the native parameters, including body when required.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"operation":{"type":"string","enum":["activity.list","analytics","analytics.explore","assistant.approvals","automations.list","campaigns.get","campaigns.list","campaigns.message","campaigns.recipients","campaigns.scheduled","contacts.export","contacts.get","contacts.history","contacts.list","contacts.preview","contacts.query","contacts.tags","dashboard","data.get","data.history","data.preview","drafts.get","drafts.list","email.experiment","email.gmail.connections","email.policy.get","email.preview","email.senders","email.templates.list","events.history","events.preview","events.revisions","events.sources","flows.get","flows.list","flows.validate","folders.list","inbox.capabilities","inbox.conversations","inbox.media","inbox.messages","library.list","lists.list","notifications.status","permissions.history","permissions.list","reply_rules.list","reports.get","settings.get","sms.connections","sms.senders","views.get","whatsapp.accounts","whatsapp.senders","whatsapp.templates.list","whatsapp.templates.preview"]},"parameters":{"type":"object","description":"Exact native parameters from capability discovery; omit for parameterless operations."}},"required":["operation"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/configure_marketing":{"post":{"operationId":"configure_marketing","summary":"Prepare inert drafts, local templates, folders and preferences","description":"Prepare inert drafts, local templates, folders and preferences. Does not authorize sending. Uses the same engine as /audiences. Call get_marketing_capabilities(operation=...) for the native parameters, including body when required.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"operation":{"type":"string","enum":["drafts.save","email.templates.delete","email.templates.save","events.create","flows.create","flows.draft","folders.archive","folders.create","folders.move_item","folders.rename","lists.create","views.save","whatsapp.account_profile","whatsapp.official.duplicate","whatsapp.templates.create","whatsapp.templates.delete","whatsapp.templates.duplicate","whatsapp.templates.update"]},"parameters":{"type":"object","description":"Exact native parameters from capability discovery; omit for parameterless operations."}},"required":["operation"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/execute_marketing":{"post":{"operationId":"execute_marketing","summary":"Operate live marketing: contacts/imports (may trigger existing automations), campaigns, schedules, reports, official ...","description":"Operate live marketing: contacts/imports (may trigger existing automations), campaigns, schedules, reports, official Meta templates, flows, inbox replies and event connections. Can send to real people. Use only for the user's authorized operation. Read the exact schema first. A queued receipt is NOT delivery; inspect campaign/event/flow results. Uses the same engine as /audiences. Call get_marketing_capabilities(operation=...) for the native parameters, including body when required.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"operation":{"type":"string","enum":["agents.create_reply","assistant.decide","assistant.ensure","automations.create","automations.update","campaigns.email","campaigns.run","campaigns.schedule","campaigns.sms","campaigns.whatsapp","contacts.import_file","contacts.import_text","contacts.upsert","data.contact","data.restore","data.save","email.confirmation","email.domain.activate","email.gmail.activate","email.gmail.connect","email.policy.save","email.test","events.configure","events.install_app","events.retry","flows.approve","flows.archive","flows.control","flows.launch","flows.update","inbox.flow","inbox.reply","lists.delete","lists.from_filters","notifications.queue","reply_rules.delete","reply_rules.save","reports.update","settings.update","whatsapp.bind_agent","whatsapp.official.create","whatsapp.official.delete","whatsapp.official.edit","whatsapp.refresh_names","whatsapp.templates.submit","whatsapp.test"]},"parameters":{"type":"object","description":"Exact native parameters from capability discovery; omit for parameterless operations."}},"required":["operation"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/get_voice_capabilities":{"post":{"operationId":"get_voice_capabilities","summary":"Discover Fine Structure business voice agents: flows, templates, voices, rules, permissions, confirmed leads, qualifi...","description":"Discover Fine Structure business voice agents: flows, templates, voices, rules, permissions, confirmed leads, qualification, analytics, optimization, native handoffs, signed webhooks and phone routing. Operator entitlement and explicit account voice scopes required. Request an operation for its exact schema, or topic=guide for the end-to-end workflow.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"operation":{"type":"string","enum":["activity.get","analytics.optimize","analytics.report","calls.get","calls.list","connections.activity","connections.catalog","connections.preview","connections.retry","connections.status","documents.validate","knowledge.documents","knowledge.excerpt","leads.analyze","leads.export","leads.get","leads.list","leads.update","phone.call_owner","phone.connect","phone.lines","phone.options","profiles.author","profiles.control","profiles.create","profiles.get","profiles.list","profiles.publish","profiles.save","requests.update","revisions.get","revisions.list","revisions.restore","runs.get","service.catalog","service.check","service.configure","service.entities","service.get","service.propose","service.reconcile","simulation.start","simulation.turn","templates.create","templates.get","templates.list","templates.status","templates.update","voices.list","webhook.configure","webhook.get","webhook.retry"]},"topic":{"type":"string","enum":["operations","guide","document_schema"]}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/read_voice":{"post":{"operationId":"read_voice","summary":"Read scoped voice configuration, live calls and transcripts, lead data, analytics or provider number inventory","description":"Read scoped voice configuration, live calls and transcripts, lead data, analytics or provider number inventory. Does not place calls or change configuration. Discover exact parameters with get_voice_capabilities first.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"operation":{"type":"string","enum":["activity.get","analytics.report","calls.get","calls.list","connections.activity","connections.catalog","connections.preview","documents.validate","knowledge.documents","knowledge.excerpt","leads.export","leads.get","leads.list","phone.lines","phone.options","profiles.get","profiles.list","revisions.get","revisions.list","runs.get","service.catalog","service.check","service.entities","service.get","templates.get","templates.list","voices.list","webhook.get"]},"parameters":{"type":"object"}},"required":["operation"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/configure_voice":{"post":{"operationId":"configure_voice","summary":"Build drafts/templates, simulate, qualify leads, update captured request stages with version checking and propose opt...","description":"Build drafts/templates, simulate, qualify leads, update captured request stages with version checking and propose optimization. AI operations incur usage. Does not publish or connect phone/webhook destinations. Discover exact parameters with get_voice_capabilities first.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"operation":{"type":"string","enum":["analytics.optimize","leads.analyze","leads.update","profiles.author","profiles.create","profiles.save","requests.update","revisions.restore","service.propose","simulation.start","simulation.turn","templates.create","templates.status","templates.update"]},"parameters":{"type":"object"}},"required":["operation"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/execute_voice":{"post":{"operationId":"execute_voice","summary":"Operate live voice agents: publish, pause, change routing, connect webhook destinations, retry handoffs or call the v...","description":"Operate live voice agents: publish, pause, change routing, connect webhook destinations, retry handoffs or call the verified owner. Can spend money and reach external systems. Requires the user's authorization; a queued/accepted handoff is not customer delivery. Discover exact parameters with get_voice_capabilities first.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"operation":{"type":"string","enum":["connections.retry","connections.status","phone.call_owner","phone.connect","profiles.control","profiles.publish","service.configure","service.reconcile","webhook.configure","webhook.retry"]},"parameters":{"type":"object"}},"required":["operation"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"fse2_mcp_<token>","description":"User-created Fine Structure token. Create one self-serve at https://finestructure.ai/api-keys. Tokens are scoped by account, app and permissions."}},"schemas":{"ToolResult":{"type":"object","properties":{"ok":{"type":"boolean"},"tool":{"type":"string"},"result":{"type":"object","additionalProperties":true}},"required":["ok","tool","result"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"JsonRpcRequest":{"type":"object","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"integer"},{"type":"null"}]},"method":{"type":"string","enum":["initialize","tools/list","tools/call"]},"params":{"type":"object","additionalProperties":true}},"required":["jsonrpc","method"]}}},"externalDocs":{"description":"Agent integration guide","url":"https://finestructure.ai/api/mcp/docs"}}