master-ai/platform/contracts/tool-registry.yaml

version: 1

tools:

  # ----------------------------
  # CODE / DEPLOYMENT
  # ----------------------------

  cloudrun.deploy_service:
    description: Build and deploy a Cloud Run service using Cloud Build. Returns the service URL and deployed revision.
    risk: medium
    executor:
      kind: http
      url: https://deploy-executor-REPLACE.a.run.app
      path: /execute/cloudrun/deploy
    inputSchema:
      type: object
      additionalProperties: false
      required: [service_name, repo, ref, env, region]
      properties:
        service_name:
          type: string
          minLength: 1
          description: Cloud Run service name.
        repo:
          type: string
          minLength: 1
          description: Git repo URL (HTTPS).
        ref:
          type: string
          minLength: 1
          description: Git ref (branch/tag/SHA).
        env:
          type: string
          enum: [dev, staging, prod]
        region:
          type: string
          minLength: 1
          description: GCP region for the Cloud Run service (e.g., us-central1).
    outputSchema:
      type: object
      properties:
        service_url:
          type: string
        revision:
          type: string

  cloudrun.get_service_status:
    description: Fetch Cloud Run service status including latest revision and URL.
    risk: low
    executor:
      kind: http
      url: https://deploy-executor-REPLACE.a.run.app
      path: /execute/cloudrun/status
    inputSchema:
      type: object
      additionalProperties: false
      required: [service_name, region]
      properties:
        service_name:
          type: string
          minLength: 1
        region:
          type: string
          minLength: 1
    outputSchema:
      type: object
      properties:
        service_name:
          type: string
        region:
          type: string
        service_url:
          type: string
        latest_ready_revision:
          type: string
        status:
          type: string
          enum: [ready, deploying, error, unknown]

  logs.tail:
    description: Tail recent logs for a Cloud Run service or for a specific run_id.
    risk: low
    executor:
      kind: http
      url: https://observability-executor-REPLACE.a.run.app
      path: /execute/logs/tail
    inputSchema:
      type: object
      additionalProperties: false
      required: [scope, limit]
      properties:
        scope:
          type: string
          enum: [service, run]
        service_name:
          type: string
        region:
          type: string
        run_id:
          type: string
        limit:
          type: integer
          minimum: 1
          maximum: 2000
          default: 200
    outputSchema:
      type: object
      properties:
        lines:
          type: array
          items:
            type: object
            properties:
              timestamp:
                type: string
              severity:
                type: string
              text:
                type: string

  # ----------------------------
  # COMPANY BRAIN (BRAND + STYLE)
  # ----------------------------

  brand.get_profile:
    description: Retrieve the tenant's brand profile (voice, tone, positioning, compliance constraints).
    risk: low
    executor:
      kind: http
      url: https://firestore-executor-REPLACE.a.run.app
      path: /execute/brand/get_profile
    inputSchema:
      type: object
      additionalProperties: false
      required: [profile_id]
      properties:
        profile_id:
          type: string
          minLength: 1
          description: Brand profile identifier (e.g., "default").
    outputSchema:
      type: object
      properties:
        profile_id:
          type: string
        brand:
          type: object

  brand.update_profile:
    description: Update the tenant's brand profile. Write operations should be validated and audited.
    risk: medium
    executor:
      kind: http
      url: https://firestore-executor-REPLACE.a.run.app
      path: /execute/brand/update_profile
    inputSchema:
      type: object
      additionalProperties: false
      required: [profile_id, patch]
      properties:
        profile_id:
          type: string
          minLength: 1
        patch:
          type: object
          description: Partial update object; executor must validate allowed fields.
    outputSchema:
      type: object
      properties:
        ok:
          type: boolean
        updated_at:
          type: string

  # ----------------------------
  # ANALYTICS / CAUSATION
  # ----------------------------

  analytics.funnel_summary:
    description: Return funnel metrics for a time window. Uses curated events in BigQuery.
    risk: low
    executor:
      kind: http
      url: https://analytics-executor-REPLACE.a.run.app
      path: /execute/analytics/funnel_summary
    inputSchema:
      type: object
      additionalProperties: false
      required: [range_days, funnel]
      properties:
        range_days:
          type: integer
          minimum: 1
          maximum: 365
        funnel:
          type: object
          required: [name, steps]
          properties:
            name:
              type: string
            steps:
              type: array
              minItems: 2
              items:
                type: object
                required: [event_name]
                properties:
                  event_name:
                    type: string
    outputSchema:
      type: object
      properties:
        funnel_name:
          type: string
        range_days:
          type: integer
        steps:
          type: array

  analytics.top_drivers:
    description: Identify top correlated drivers for a target metric/event.
    risk: low
    executor:
      kind: http
      url: https://analytics-executor-REPLACE.a.run.app
      path: /execute/analytics/top_drivers
    inputSchema:
      type: object
      additionalProperties: false
      required: [range_days, target]
      properties:
        range_days:
          type: integer
          minimum: 1
          maximum: 365
        target:
          type: object
          required: [metric]
          properties:
            metric:
              type: string
            event_name:
              type: string
    outputSchema:
      type: object
      properties:
        target:
          type: object
        range_days:
          type: integer
        drivers:
          type: array

  analytics.write_insight:
    description: Persist an insight object (BigQuery table + Firestore pointer + GCS artifact).
    risk: medium
    executor:
      kind: http
      url: https://analytics-executor-REPLACE.a.run.app
      path: /execute/analytics/write_insight
    inputSchema:
      type: object
      additionalProperties: false
      required: [insight]
      properties:
        insight:
          type: object
          required: [type, title, summary, severity, confidence, window, recommendations]
          properties:
            type:
              type: string
              enum: [funnel_drop, anomaly, driver, experiment_result, general]
            title:
              type: string
            summary:
              type: string
            severity:
              type: string
              enum: [info, low, medium, high, critical]
            confidence:
              type: number
              minimum: 0
              maximum: 1
            window:
              type: object
            recommendations:
              type: array
    outputSchema:
      type: object
      properties:
        insight_id:
          type: string
        stored:
          type: object

  # ----------------------------
  # MARKETING (GENERATION + PUBLISH)
  # ----------------------------

  marketing.generate_channel_posts:
    description: Generate platform-specific social posts from a campaign brief + brand profile.
    risk: low
    executor:
      kind: http
      url: https://marketing-executor-REPLACE.a.run.app
      path: /execute/marketing/generate_channel_posts
    inputSchema:
      type: object
      additionalProperties: false
      required: [brief, channels, brand_profile_id]
      properties:
        brand_profile_id:
          type: string
        brief:
          type: object
          required: [goal, product, audience, key_points]
          properties:
            goal:
              type: string
            product:
              type: string
            audience:
              type: string
            key_points:
              type: array
              items:
                type: string
        channels:
          type: array
          items:
            type: string
            enum: [x, linkedin, facebook, instagram, tiktok, youtube, pinterest, reddit]
        variations_per_channel:
          type: integer
          minimum: 1
          maximum: 10
          default: 3
    outputSchema:
      type: object
      properties:
        channels:
          type: array

  marketing.publish_missinglettr:
    description: Publish or schedule a campaign via Missinglettr.
    risk: medium
    executor:
      kind: http
      url: https://marketing-executor-REPLACE.a.run.app
      path: /execute/marketing/publish_missinglettr
    inputSchema:
      type: object
      additionalProperties: false
      required: [campaign, schedule]
      properties:
        campaign:
          type: object
          required: [name, posts]
          properties:
            name:
              type: string
            posts:
              type: array
              items:
                type: object
                required: [channel, text]
                properties:
                  channel:
                    type: string
                  text:
                    type: string
                  media_urls:
                    type: array
                    items:
                      type: string
        schedule:
          type: object
          required: [mode]
          properties:
            mode:
              type: string
              enum: [now, scheduled]
            start_time:
              type: string
            timezone:
              type: string
              default: UTC
    outputSchema:
      type: object
      properties:
        provider:
          type: string
        campaign_id:
          type: string
        status:
          type: string
          enum: [queued, scheduled, published, failed]