Create Deal

Title of the deal. REQUIRED. Should be a short, descriptive label for the business opportunity. If the user does not provide a title, generate one automatically as 'Novo Negócio - {contact_name}'. Example values: 'Venda Apt 302 - João Silva', 'Locação Sala Comercial Centro'.

Exact display name of the pipeline group where the deal will be created. Required. A pipeline group is the funnel that contains stages, while stage_name identifies a step inside that funnel. Remove the word 'Funil' from user input: 'funil de Vendas' → 'Vendas', 'funil de Locação' → 'Locação', and 'Funil de Vendas & Locação' → 'Vendas & Locação'. Do not send a short prefix such as VEN. If the exact name is not found, the tool returns pipeline group options.

Stage where the deal starts inside pipeline_group_name. Required. A stage is a step inside the selected pipeline group, not the funnel itself. If the user does not specify a stage, send 'primeira etapa' to select the first stage. Stage comparison ignores case, diacritics, and special characters. For creation, an unknown stage currently falls back to the first stage and the response reports that fallback. Examples: 'Novo Lead', 'Visita Agendada', 'Proposta Enviada', 'Negociação', 'Fechamento'.

Monetary value of the deal in BRL (Brazilian Reais). REQUIRED. Send as a plain number WITHOUT currency symbols or thousand separators. Use dot as decimal separator. If the user does not specify a value, send 0. For rent deals this is the monthly rent value. For buy deals this is the total sale price. Example values: 0, 350000.00, 2500.50, 1200000.

Type of business interest for this deal. Defaults to 'buy'. Send one of the exact slug values — NOT Portuguese. Translation map: compra / venda → 'buy', aluguel / locação → 'rent', temporada / aluguel por temporada → 'vacation_rental'. For interest='vacation_rental', provide both vacation_start and vacation_end.

Start date of the vacation rental period. Provide it when interest='vacation_rental'; it is ignored otherwise. Format: ISO 8601 datetime string. Example: '2026-11-20T00:00:00.000Z'.

End date of the vacation rental period. Provide it when interest='vacation_rental'; it is ignored otherwise. Must be after vacation_start. Format: ISO 8601 datetime string. Example: '2026-11-30T00:00:00.000Z'.

Free-text notes or additional details about the deal. Can include property preferences, client requirements, negotiation context, etc. No format restrictions. Example: 'Cliente procura apartamento 3 quartos, vista para o mar, orçamento máximo de 500 mil'.

Email of the contact (person or organization) to link to this deal. The tool resolves the contact and detects whether it is a person or organization. Prefer this over contact_name — it is more precise and avoids ambiguity when multiple contacts share similar names. If both contact_email and contact_name are provided, both are used in the search (AND logic). Format: user@domain.com. Example: 'joao.silva@gmail.com'.

Full name of the contact to link to this deal. Use it when contact_email is unavailable or to narrow the lookup. The name must match exactly one contact — if multiple contacts match, the backend returns an error listing them for disambiguation. Example values: 'João Silva', 'Construtora ABC Ltda'.

Phone number of the contact to link to this deal. Used as an additional filter to identify the contact when email or name are not sufficient. It must match exactly one contact. Format: 11 91234-5678. Example: '11 91234-5678'.

Legal identification of the contact, such as CPF for individuals or CNPJ for companies. Used as an additional filter to identify the contact when email or name are not sufficient. It must match exactly one contact. Example values: '123.456.789-00' for CPF, '12.345.678/0001-00' for CNPJ.

Exact public code of the contact to link. Use it when the contact is already identified by code. The runtime may also populate it automatically when the contact was created or selected in the same conversation. Examples: '12345', 'CON-001'.

Internal Firestore document ID of the pipeline group, injected automatically by the runtime during stage disambiguation. Do NOT populate this field manually. When present, it bypasses the name-based pipeline group lookup so that a retry after stage disambiguation always resolves the same funnel regardless of any inconsistency between the user-provided name and the database.

Initial status of the deal. Almost always 'in progress' for new deals. Only change this if the user explicitly asks to create a deal as already won or lost. Allowed values: 'in progress', 'win', 'lost'. Note: this field uses SPACES ('in progress'), not underscores.

Responsible broker name or partial name. The lookup is case-insensitive and considers active users. It must resolve to exactly one user; otherwise the tool returns options for disambiguation. Omit both user_name and user_email to keep or assign the requesting user, depending on the operation. Examples: 'Maria', 'Carlos Souza'.

Responsible broker email. Exact match, case-insensitive. Preferred when available because it avoids ambiguity for duplicated names. Omit both user_email and user_name to assign the requesting user.