Search Deals

Raw deal code exactly as the user mentioned, e.g. 'AVA-12', 'VEN-42' or '12'. Use this whenever the user refers to a deal by its code — pass the full string here and the tool will extract the number and pipeline prefix automatically. Do NOT split the code manually or set deal_code / pipeline_group_prefix separately when using this field. Examples: user says 'negócio AVA-12' → deal_code_raw='AVA-12'; user says 'negócio 12' → deal_code_raw='12'.

Free-text search across the deal title, description, and custom string fields. Use dedicated contact, property, and deal-code fields when the user provides those identifiers. Send the raw text without quotes or special formatting. Examples: 'apartamento moema', 'proposta comercial'.

Numeric portion of a deal code, without letters or a hyphen. Prefer deal_code_raw when the user provides a code, because that field preserves and parses the complete value. When populating this field directly, pair it with pipeline_group_prefix or the exact pipeline_group_name. Example: 12.

Short alphanumeric prefix that identifies a pipeline group, such as AVA in AVA-12. Normally this is extracted automatically from deal_code_raw. When populated directly, use it with the numeric deal_code. It takes priority over pipeline_group_name if both are sent.

Name (or part of the name) of the person or organization associated with the deal. Substring search, case-insensitive, diacritics ignored. The tool resolves the contact before filtering deals. Use when the user asks for deals of a specific contact by name. Prefer contact_email when an email is available (more precise). Example values: 'João', 'Silva', 'Construtora ABC'.

Exact email of the person or organization linked to the deal. Case-insensitive. The tool resolves the contact and filters its deals. Prefer this over contact_name when email is known — it is more precise and avoids ambiguity with similar names. Format: user@domain.com. Example: 'maria@empresa.com'.

Exact phone number of the person or organization linked to the deal. Case-insensitive. The tool resolves the contact and filters its deals. Preferred when available because it avoids ambiguity for duplicated names. Format: +55 11 91234-5678. Example: '+55 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 person or organization linked to the deal. Use it when the contact is already identified by code; the tool resolves the contact directly and filters its associated deals.

Exact display name of the pipeline group used to filter deals. A pipeline group is the funnel that contains stages; it is not a stage. Remove the word 'Funil' from user input: 'funil de Vendas' → 'Vendas' and 'funil Locação' → 'Locação'. Do not send a short prefix such as VEN in this field. If the name is not found, the tool returns pipeline group options.

Pipeline stage name used to filter deals. A stage is a step inside a pipeline group, so combine this field with pipeline_group_name to avoid ambiguity across funnels. When a pipeline group is provided, comparison also ignores case, diacritics, and special characters. Examples: 'Proposta Enviada', 'Negociação', 'Fechamento', 'Novo Lead'.

Filter deals by their current status. Send one of the exact slug values listed below — NOT the Portuguese term. Translation map from Portuguese: em andamento / aberto → 'in progress', ganho / ganhou / fechado → 'win', perdido / perdeu → 'lost', estagnado / parado → 'stagnant', atrasado / vencido → 'out_of_date'. Example: user says 'negócios ganhos' → status='win'.

Filter by the deal interest type (what the client wants). Send one of the exact slug values — NOT Portuguese. Translation map: compra / venda → 'buy', aluguel / locação → 'rent', temporada → 'vacation_rental'. Example: user says 'negócios de locação' → deal_type='rent'.

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. When the user refers to their own deals ('meus negócios', 'minhas vendas', 'meus leads', 'minha carteira'), leave this field empty and set requesting_user_only=true. Examples: 'Maria', 'Carlos Souza'.

Responsible broker email. Exact match, case-insensitive. Preferred when available because it avoids ambiguity for duplicated names. When the user refers to their OWN deals ('meus negócios', 'minhas vendas'), do NOT set this field — use requesting_user_only=True instead.

Set to true when the user refers to their own deals using possessive language: 'meus negócios', 'minhas vendas', 'meus leads', 'minha carteira', 'meus negócios em andamento', 'minhas oportunidades'. When true, results are restricted to the requesting user's deals regardless of read permissions. Do NOT set this when the user asks about another broker's deals. If user_name or user_email is also provided, that explicit broker takes precedence.

Name of the team responsible for the deal. The tool resolves the team name. Must match exactly one team. Example values: 'Equipe Comercial', 'Time Vendas SP'.

Code of the property linked to the deal. Exact match. This is the property's own code, not the deal code. The tool resolves the property and filters deals that include it in their presented-property list. Send as string. Example values: '876', 'AP-302'.

Address (or part of the address) of the property linked to the deal. Substring search, case-insensitive. Used to find deals associated with properties at a given location. Can be combined with property_code for precision. Example values: 'Av. Paulista', 'Rua das Flores, 100'.

Filter deals by when they were CREATED. Send one of the exact keyword values — the backend converts it to a date range. Allowed values and their meaning: 'today' = created today, 'this_week' = created in the current week (Mon–Sun), 'this_month' = created in the current month, 'last_month' = created in the previous month, 'last_three_months' = created in the last 3 months, 'current_year' = created in the current year, 'last_year' = created in the previous year. Example: user says 'negócios criados esta semana' → create_period='this_week'.

Filter deals by when they were last UPDATED (any field change). Same keyword values as create_period. Use this when the user asks about recent activity or changes. Example: user says 'negócios atualizados hoje' → update_period='today'.

Opaque pagination cursor accepted by the backend. Send it only when a cursor was supplied by external context; do not invent one or send it on the first request. The current MCP tool response does not expose the next cursor.