Get all lead fields for the current tenant. CALL THIS FIRST before creating a lead. Returns a cheat sheet with API names (standard fields), Field IDs (custom fields), and Picklist Option IDs. Use this to build field_values for create_lead based on what the user wants—do not use static fields.

Get the current authenticated user's profile from Kylas (GET /users/me). Call this whenever a date or datetime-related query is involved. Returns timezone (IANA, e.g. Asia/Calcutta), recordActions (call, email, sms, etc.), name, and other profile fields.

• For filtering (search_leads, search_idle_leads): use the returned timezone as the timeZone in date/datetime filters; keep the user's date/datetime as-is (do not convert to UTC).

• For create_lead: when the user provides a datetime in their own words (e.g. "11th Feb 2026 at 7:30 AM"), interpret it in this timezone, convert to UTC using parse_datetime_to_utc_iso, and send the UTC ISO string in field_values.

Look up users by name, or list all users in the system.

• Use return_all=True (with query "name:" or empty) to fetch all users in one response (all pages combined).

• For name search: query in field:value form (e.g. "firstName:last", "name:Last"). If one user is found, use that ID in search_leads; if multiple, ask which one. query: Search string (e.g. "firstName:last", "name:Last"). Use "name:" or leave default to list all when return_all=True. page: 0-based page (default 0). Ignored when return_all=True. size: Page size, max 50 (default 50). Used per page when return_all=True. return_all: If True, fetch all pages and return every user in one response (cap 500).

Look up products by name. Use this BEFORE filtering leads by product when the user gives a product name.

• If one product is found, use that product's ID in search_leads (e.g. {"field": "products", "operator": "equal", "value": }).

• If multiple products are found, ask the user which product they mean (list the options), then use the chosen product's ID in search_leads. query: Search string. Use "name:" (e.g. "name:Widget") or just the product name (e.g. "Widget"); the server will send name:value to the API. page: 0-based page (default 0). size: Max 50 (default 50).

Look up pipelines by name (for leads). Use when the user asks for leads by stage (e.g. open/closed/won/lost) but does not specify which pipeline.

• Call this first; do NOT call get_pipeline_stages until after the user confirms the pipeline.

• Present the pipeline(s) (id and name) and ask the user which pipeline they mean. If only one pipeline is found, still ask for confirmation.

• Only after the user confirms, call get_pipeline_stages with that pipeline ID to get stages for that pipeline, then search_leads. query: Search string. Use "name:" or just the pipeline name; empty string returns all pipelines for the entity. entity_type: Entity type (default LEAD). page: 0-based page (default 0). size: Max 50 (default 50).

Get stages for a pipeline. Call this only after the user has confirmed which pipeline to use (from lookup_pipelines). Do not call before pipeline confirmation. Returns pipeline name and list of stages for that pipeline only, with id, name, and forecastingType (OPEN, CLOSED_WON, CLOSED_LOST, CLOSED_UNQUALIFIED). Use the stage IDs in search_leads: filters [{"field": "pipeline", "operator": "equal", "value": pipeline_id}, {"field": "pipelineStage", "operator": "equal", "value": stage_id}]. If the user said "open leads" or "closed leads" and more than one stage has the same forecastingType, ask which stage they mean. pipeline_id: The pipeline ID (from lookup_pipelines).

Get full pipeline details by ID (GET /pipelines/{id}): stages plus unqualifiedReasons and lostReasons. Call this when moving a lead to Closed Lost or Closed Unqualified. Present the relevant reasons list to the user, ask them to pick one, then call update_lead with pipelineStageReason set to that exact string (e.g. "No followup", "Booked with competitor"). pipeline_id: The pipeline ID (from the lead's current pipeline or from lookup_pipelines).

Parse a datetime string in the user's timezone and return UTC ISO string for the Kylas API. Call get_current_user first to get the user's timezone. Use the returned string in create_lead field_values for date/datetime fields. Example: user says "create lead with follow-up 11th Feb 2026 at 7:30 AM" → get_current_user → timezone Asia/Calcutta → parse_datetime_to_utc_iso_tool("11 Feb 2026 7:30 AM", "Asia/Calcutta") → use result in field_values. local_datetime: Datetime as the user said it (e.g. "11 Feb 2026 7:30 AM", "11th Feb 2026 at 7:30 am"). timezone: IANA timezone from get_current_user (e.g. Asia/Calcutta).

Create a lead in Kylas CRM with only the fields the user wants (no static field list).

You MUST call get_lead_field_instructions FIRST to get valid API names and Field IDs. Infer from user context which fields to send; include only those in field_values.

field_values: Map of field identifier to value.

• Standard fields: use API name as key at top level (e.g. firstName, lastName, companyName, emails, phoneNumbers, leadSource, isNew).

• Custom fields: MUST be under "customFieldValues" with internal name as key (e.g. "customFieldValues": {"cfLeadCheck": "Checked"}). Do not use field ID as key—Kylas expects internal names. If you pass a field ID (e.g. "1210985"), the server will resolve it to the internal name (e.g. cfLeadCheck) automatically.

• For a single email use "email": "user@example.com". For phones use "phone": "5551234567" (or "phoneNumbers" array) and you MUST include "phone_country_code": "IN" or "+91" at top level. If the user provided phone(s) but did not specify country or dial code, do NOT call create_lead—ask the user (e.g. which country/dial code for these numbers?) and only call after they respond. Do not infer from currency or other context. Email types: OFFICE, PERSONAL. Phone types: MOBILE, WORK, HOME, PERSONAL. Exactly one email and at most one phone should be primary; first entry is primary by default.

• For picklists use the Option ID (number) from the cheat sheet.

• For date/datetime fields: the user gives a time in their timezone (e.g. "11th Feb 2026 at 7:30 AM"). Call get_current_user, then parse_datetime_to_utc_iso_tool(local_datetime, timezone) and put the returned UTC ISO string in field_values.

Update a lead in Kylas CRM. Fetches the lead first, merges your field_values into it, then PUTs the full body. Same field_values format as create_lead. Call get_lead_field_instructions first for API names and custom field internal names. For owner: use lookup_users to get the user ID, then pass ownerId: in field_values.

lead_id: The lead ID to update (e.g. from search_leads or search_leads_by_term results). field_values: Map of field identifier to value (same as create_lead: firstName, lastName, email, phone with phone_country_code, customFieldValues, picklist Option IDs, date/datetime in UTC ISO, etc.). These are merged over the existing lead; other fields are left unchanged.

Get full details of a lead by ID (GET /leads/{id}). Use when the user asks for complete lead info, lead details, or to view a specific lead. lead_id: The lead ID (e.g. from search_leads or search_leads_by_term results).

Search/filter leads. Only fields marked [FILTERABLE] in get_lead_field_instructions can be used. Call get_lead_field_instructions first to get filterable fields and their types.

filters: List of filter objects. Each must have:

• field (str): Field internal/API name (e.g. firstName, country, source, createdAt).

• operator (str): One of the allowed operators for that field type (e.g. equal, contains, greater).

• value: Value to compare. For PICK_LIST/MULTI_PICKLIST use Option ID (number), except requirementCurrency, companyBusinessType, country, timezone, companyIndustry — use internal name (string). For date/datetime (incl. custom e.g. cfDateField): value null for today/is_null/is_not_null; single ISO string for greater/greater_or_equal/less/less_or_equal e.g. "2026-02-02T18:30:00.000Z"; for between use [startISO, endISO].

• timeZone (str, optional): For date/datetime filters only; default from server or env.

• type (str, optional): Field type from cheat sheet. If omitted, inferred from schema. For user look-up fields (createdBy, updatedBy, convertedBy, ownerId, importedBy): value must be user ID (number). Call lookup_users first. For the products field: value must be product ID (number). Call lookup_products first; if multiple matches, ask which product, then use that ID here. For pipeline / pipelineStage (e.g. open leads, closed leads): call lookup_pipelines first, ask the user to confirm which pipeline, then call get_pipeline_stages for that pipeline only; if stage is ambiguous ask which stage, then use pipeline + pipelineStage filters here. page: 0-based page (default 0). size: Page size, max 100 (default 20). sort: Sort e.g. "createdAt,desc" (default).

Operators by type (examples): TEXT_FIELD: equal, contains, is_empty. NUMBER: equal, greater, between, is_null. PICK_LIST: equal, in, is_null. DATETIME_PICKER: today, yesterday, between, is_not_null, greater, less, current_week, etc.

Search leads by a single term across multiple fields (firstName, lastName, companyName, phoneNumbers, emails, etc.). Use this when the user asks for "leads with X", "leads containing Y", or "leads named Z" without specifying which field to filter on. For filtering by a specific field (e.g. "leads where phone number is X"), use search_leads instead.

search_term: The term to search for (e.g. "akshay", "acme"). page: 0-based page (default 0). size: Page size, max 100 (default 20). sort: Sort e.g. "updatedAt,desc" (default).

Search for idle/stagnant leads: no activity for at least the given number of days. Uses both updatedAt and latestActivityCreatedAt; a lead is returned only when BOTH dates are on or before (today − days), so the effective last activity is before the threshold.

days: Minimum days with no activity (e.g. 10 for "no activity since 10 days"). time_zone: IANA timezone for threshold (e.g. America/New_York). Default: Asia/Calcutta. page: 0-based page (default 0). size: Page size, max 100 (default 20). sort: Sort e.g. "createdAt,desc" (default).