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.

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).

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 "phone": "5551234567" and optionally "phone_country_code": "+1".

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

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 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).