create_deal

Semantics

Creates a Deal row linked to the contact, with title, estimated value (optional), and starting in stage `new`. Subsequent stage transitions (`qualifying`, `proposal`, `won`, `lost`) are owner-driven and not exposed via this capability.

Invariants

• The contact must exist. If contact_email is not found, returns `unknown_contact` with the same wrong-tenant hint mechanism as `log_activity`.
• Deal title is required.
• If estimated_value_cents is provided, currency must be provided too.

When to use

When the user is starting to pursue a sale with a known contact — after `find_contact` or `create_contact`. Tracks the opportunity in the CRM pipeline so the owner can move it through stages.

Input schema

{
  "type": "object",
  "required": [
    "contact_email",
    "title"
  ],
  "properties": {
    "title": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1
    },
    "currency": {
      "type": "string",
      "description": "ISO 4217. Required if estimated_value_cents is provided."
    },
    "description": {
      "type": "string",
      "maxLength": 5000
    },
    "agent_vendor": {
      "type": "string"
    },
    "contact_email": {
      "type": "string",
      "format": "email"
    },
    "expected_close_date": {
      "type": "string",
      "format": "date"
    },
    "estimated_value_cents": {
      "type": "number",
      "minimum": 0
    }
  },
  "additionalProperties": false
}

Output schema

{
  "type": "object",
  "required": [
    "ok"
  ],
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "error": {
      "enum": [
        "unknown_contact",
        "wrong_tenant",
        "invalid_input"
      ],
      "type": "string"
    },
    "stage": {
      "enum": [
        "new",
        "qualifying",
        "proposal",
        "won",
        "lost"
      ],
      "type": "string"
    },
    "deal_id": {
      "type": "string"
    },
    "contact_id": {
      "type": "string"
    }
  }
}

Recent conformance runs