{"name":"CloutOps Agent Connector","version":"0.1.0","protocol":"cloutops-agent-tools/v1","description":"Machine-readable tool catalog for AI assistants that orchestrate CloutOps as a managed media workflow: workspace setup, campaign intake, audience routing, creative production, quote/approval, placement proof, reporting, and invoices.","auth":{"current":"api_key_required","configured":true,"scopes":["agent:read","agent:plan"],"organizationScoped":true,"acceptedHeaders":["Authorization: Bearer <token>","x-cloutops-agent-key"],"productionRequirement":"Set CLOUTOPS_AGENT_API_KEY, CLOUTOPS_AGENT_SCOPES, and CLOUTOPS_AGENT_ORGANIZATION_ID before exposing stateful customer tools."},"endpoints":{"tools":"https://client.cloutos.com/api/agent/tools","openapi":"https://client.cloutos.com/api/agent/openapi","connectionKit":"https://client.cloutos.com/api/agent/connection-kit","mediaPlan":"https://client.cloutos.com/api/agent/plan"},"workflow":[{"id":"workspace_setup","label":"Workspace setup","buyerValue":"Confirm brand, billing, reporting, approval, and constraint context before campaign planning starts.","agentCan":["summarize workspace readiness","identify missing setup fields","prepare onboarding follow-ups"],"humanGate":"Agents cannot create final billing commitments or change organization roles."},{"id":"campaign_intake","label":"Campaign intake","buyerValue":"Turn a product, audience, budget, timing, and claims context into a usable campaign room.","agentCan":["create draft campaign intake","refine brief fields","summarize brand exclusions and claims boundaries"],"humanGate":"Budget changes, final scope, and regulated-claim approval remain human-reviewed."},{"id":"audience_route","label":"Audience route","buyerValue":"Recommend audience pools, example pages, backup supply, creative formats, and route assumptions.","agentCan":["search supply","generate modeled route recommendations","compare requested pages with audience pools"],"humanGate":"Agents cannot book spend, guarantee specific pages, or contact supply owners."},{"id":"creative_production","label":"Creative production","buyerValue":"Translate existing assets into native meme, news, carousel, reel, story, and creator-read packages.","agentCan":["recommend formats","prepare creative work orders","summarize claims/disclosure requirements"],"humanGate":"Final creative approval and placement authorization require named human approval."},{"id":"quote_approval","label":"Quote and approval","buyerValue":"Package route, creative scope, modeled delivery, quote assumptions, caveats, and makegood language.","agentCan":["prepare quote request context","fetch route dossiers","submit recommendation notes to approval gates"],"humanGate":"Agents cannot accept quotes, issue invoices, or authorize spend."},{"id":"placement_proof_reporting","label":"Placement, proof, and reporting","buyerValue":"Track live placements, proof packets, metric source labels, sentiment, organic lift, invoices, and reporting sync.","agentCan":["read proof/report/invoice state","summarize modeled versus verified metrics","flag missing proof or sync issues"],"humanGate":"Publishing reports, validating makegoods, and changing invoice state remain human-controlled."}],"allowedActions":["search scoped audience supply","draft campaign intake","update non-consequential brief fields","generate modeled media route recommendations","recommend creative production formats","prepare route/quote context for human review","read scoped reports, invoices, dossiers, packets, and approvals","submit approval recommendations without deciding the gate"],"metricTrustRules":["Every estimate should carry a metric source label such as PROFILE_SCRAPED, MODELED_ESTIMATE, OPS_ENTERED, BOOKED, VERIFIED_LIVE, VERIFIED_PERFORMANCE, PINK58_SYNC, or UNAVAILABLE_STALE.","Inventory preview numbers prove supply direction, not guaranteed delivery.","Route numbers are modeled until placements are booked and live performance snapshots are captured.","Pink58 sync is preferred when configured; local snapshots keep dashboards usable when Pink58 is unavailable."],"safety":{"defaultMode":"draft","defaultProductMode":"managed_service","specificPages":"Specific pages can be requested, but availability, pricing, timing, backup supply, and creative fit are confirmed by CloutOps ops before booked spend.","cpmPolicy":"CPM is route-based and contingent on content, rights, page mix, timing, availability, and approval state.","reportingPolicy":"Modeled metrics must stay labeled until live proof or Pink58/verified performance snapshots exist.","approvalRequiredFor":["booking placements","final pricing","restricted inventory","route approval","quote acceptance","final creative approval","placement authorization","client-facing reports","invoice issuance"],"prohibitedDirectActions":["book placements","contact page owners","accept quotes","change budgets","approve final creative","publish reports","issue invoices","override compliance restrictions"]},"tools":[{"name":"search_audience_supply","method":"GET","path":"/api/inventory","category":"supply","workflowStage":"audience_route","description":"Search public CloutOps audience supply by niche, audience, campaign goal, and format. Results are usable supply examples, not guaranteed booked placements.","returns":["example inventory pages","audience/niche signals","modeled supply metrics"],"approvalRequired":false},{"name":"create_campaign","method":"POST","path":"/api/agent/campaigns","category":"campaign","workflowStage":"campaign_intake","description":"Create a client campaign intake through an org-scoped agent token. Drafts route, starter creative variants, approval gates, ops tasks, and draft invoice without booking spend.","returns":["campaign room","intake record","starter route","starter creative variants","approval gates"],"approvalRequired":true},{"name":"update_campaign_intake","method":"PATCH","path":"/api/agent/campaigns/{campaignId}","category":"campaign","workflowStage":"campaign_intake","description":"Update non-consequential campaign intake fields. Budget changes are captured as approval requests, not applied directly.","returns":["updated campaign intake","audit/provenance context"],"approvalRequired":true},{"name":"generate_media_plan","method":"POST","path":"/api/agent/plan","category":"planning","workflowStage":"audience_route","description":"Generate a draft media route with audience pools, example pages, creative units, managed-plan risk notes, and approval gates.","returns":["audience pools","example pages","creative units","commercial estimate","approval gates"],"approvalRequired":false},{"name":"generate_media_route","method":"POST","path":"/api/agent/plan","category":"planning","workflowStage":"audience_route","description":"Generate a route-style media recommendation with modeled reach/views, sample pages, backup logic, source labels, and caveats. Does not book spend.","returns":["route recommendation","modeled numbers","backup supply","route caveats"],"approvalRequired":false},{"name":"recommend_creative_formats","method":"POST","path":"/api/agent/plan","category":"creative","workflowStage":"creative_production","description":"Recommend native creative formats, required inputs, claims/disclosure checks, and approval needs for a campaign brief.","returns":["format recommendations","required inputs","approval needs","route handoff notes"],"approvalRequired":false},{"name":"prepare_quote_request","method":"POST","path":"/api/agent/plan","category":"commercials","workflowStage":"quote_approval","description":"Prepare route-based quote assumptions for human review without accepting pricing or booking spend.","returns":["quote assumptions","commercial estimate","approval gates"],"approvalRequired":true},{"name":"create_campaign_brief","method":"POST","path":"/api/briefs","category":"lead_intake","workflowStage":"campaign_intake","description":"Create a campaign brief for ops review and follow-up planning.","returns":["lead brief","ops follow-up queue"],"approvalRequired":false},{"name":"request_page_placement","method":"POST","path":"/api/placements/request","category":"supply","workflowStage":"audience_route","description":"Request a specific page placement for ops confirmation. Availability and final pricing are not guaranteed.","returns":["placement request","ops confirmation requirement"],"approvalRequired":true},{"name":"request_specific_pages","method":"POST","path":"/api/placements/request","category":"supply","workflowStage":"audience_route","description":"Attach specific page requests to a managed plan for ops confirmation. These requests do not override route fit, availability, or final pricing.","returns":["specific page request","managed route context"],"approvalRequired":true},{"name":"get_campaign_report","method":"GET","path":"/api/agent/campaigns/{campaignId}/report","category":"reporting","workflowStage":"placement_proof_reporting","description":"Read normalized campaign reporting, provider/sync status, metric source labels, sentiment, placement metrics, creative metrics, snapshot history, and organic lift signals.","returns":["summary metrics","provider status","sync status","placement metrics","creative metrics","sentiment","organic lift"],"approvalRequired":false},{"name":"get_client_launch_plan","method":"GET","path":"/api/agent/launch-plan","category":"workspace","workflowStage":"workspace_setup","description":"Read the workspace-level client launch plan with readiness, next owner, buyer actions, risks, meeting agenda, operating rules, and links to campaign packets.","returns":["workspace readiness","buyer actions","CloutOps actions","risks","packet links"],"approvalRequired":false},{"name":"get_first_five_operating_packet","method":"GET","path":"/api/agent/first-five","category":"workspace","workflowStage":"workspace_setup","description":"Read the delivery operating packet: route dossier, creative production, supply availability, campaign room, and finance/proof readiness across the workspace.","returns":["operating readiness","buyer inputs","CloutOps outputs","approval artifacts","missing checks","campaign room links"],"approvalRequired":false},{"name":"get_route_dossier","method":"GET","path":"/api/agent/campaigns/{campaignId}/route-dossier","category":"planning","workflowStage":"quote_approval","description":"Read the exportable route approval dossier with audience rationale, page targets, backups, source labels, caveats, quote assumptions, and approval gates.","returns":["route approval dossier","modeled vs verified notes","page examples","backups","quote assumptions"],"approvalRequired":false},{"name":"get_campaign_launch_packet","method":"GET","path":"/api/agent/campaigns/{campaignId}/launch-packet","category":"campaign","workflowStage":"quote_approval","description":"Read the executive launch packet that combines route, creative production, supply/backups, campaign room state, proof/reporting, finance, approvals, and agent-safe next actions.","returns":["campaign command summary","delivery workflow state","agent-safe next actions"],"approvalRequired":false},{"name":"get_creative_production_packet","method":"GET","path":"/api/agent/campaigns/{campaignId}/creative-packet","category":"creative","workflowStage":"creative_production","description":"Read the campaign-level creative production packet with source assets, native formats, claims/disclosure needs, creative package readiness, approvals, and route handoff.","returns":["creative work order","format system","source asset state","claims/disclosures","route handoff"],"approvalRequired":false},{"name":"get_creative_template_library","method":"GET","path":"/api/agent/creative-templates","category":"creative","workflowStage":"creative_production","description":"Read the reusable creative template library for meme, news, text-over-video, and mixed-carousel packages, including required inputs, approval checks, handoff packages, and agent-safe brief fields.","returns":["template library","required inputs","production fields","approval checks","route handoff rules","agent-safe usage rules"],"approvalRequired":false},{"name":"request_creative_production","method":"POST","path":"/api/agent/campaigns/{campaignId}/creative-requests","category":"creative","workflowStage":"creative_production","description":"Create a draft native creative production request from an org-scoped agent token. Produces a draft creative packet, export spec, ops task, and audit record without approving final creative or booking spend.","returns":["draft creative variant","creative decision packet","ops production task","human approval guardrails"],"approvalRequired":true},{"name":"get_invoice_status","method":"GET","path":"/api/agent/invoices/{invoiceId}","category":"finance","workflowStage":"placement_proof_reporting","description":"Read the commercial packet for an invoice: quote/IO scope, line items, PO and signed-document context, proof evidence, payment state, makegoods, source labels, and readiness checks.","returns":["commercial packet","invoice status","quote/IO context","line items","payment records","proof evidence","makegoods"],"approvalRequired":false},{"name":"submit_approval","method":"POST","path":"/api/agent/approvals/{approvalId}","category":"approvals","workflowStage":"quote_approval","description":"Submit an agent recommendation for a route, creative variant, placement, report, or invoice approval. The approval gate is not decided until an authorized human acts.","returns":["approval recommendation","audit entry"],"approvalRequired":true},{"name":"get_approval_packet","method":"GET","path":"/api/agent/approvals/{approvalId}/packet","category":"approvals","workflowStage":"quote_approval","description":"Read the exportable approval packet with subject summary, named approvers, timing, guardrails, decision notes, and audit trail.","returns":["approval packet","subject snapshot","audit trail","guardrails"],"approvalRequired":false},{"name":"enrich_inventory_page","method":"POST","path":"/api/enrich","category":"supply","workflowStage":"audience_route","description":"Queue enrichment for profile data, captions, metrics, and classification updates.","returns":["enrichment job result","updated inventory classification when available"],"approvalRequired":true}]}