Create a new Lead in EspoCRM.

This tool creates a Lead record using common Lead fields, parameters map to EspoCRM Lead attributes.
Any parameter set to `None` is omitted from the request to avoid overwriting defaults.

Args:
- `salutation_name` (Optional[str]): Salutation (e.g. 'Mr.', 'Ms.', 'Dr.').
- `first_name` (Optional[str]): First name (<= 100 chars).
- `middle_name` (Optional[str]): Middle name (<= 100 chars).
- `last_name` (Optional[str]): Last name (<= 100 chars).
- `title` (Optional[str]): Job title (<= 100 chars).
- `status` (Optional[str]): Lead status (New, Assigned, In Process, Converted, Recycled, Dead).
- `source` (Optional[str]): Lead source (Call, Email, Campaign, etc.).
- `industry` (Optional[str]): Industry (see API allowed values).
- `opportunity_amount` (Optional[float]): Opportunity amount (>= 0).
- `opportunity_amount_currency` (Optional[str]): Currency code (USD, EUR).
- `website` (Optional[str]): Website (<= 255 chars).
- `address_street` (Optional[str]): Street (<= 255 chars).
- `address_city` (Optional[str]): City (<= 100 chars).
- `address_state` (Optional[str]): State (<= 100 chars).
- `address_country` (Optional[str]): Country (<= 100 chars).
- `address_postal_code` (Optional[str]): Postal code (<= 40 chars).
- `email_address` (Optional[str]): Primary email (<= 255 chars).
- `email_address_data` (Optional[List[Dict[str, Any]]]): Multiple email objects.
- `phone_number` (Optional[str]): Primary phone (<= 36 chars).
- `phone_number_data` (Optional[List[Dict[str, Any]]]): Multiple phone objects.
- `do_not_call` (Optional[bool]): Do not call flag.
- `description` (Optional[str]): Description / notes.
- `account_name` (Optional[str]): Account name (<= 255 chars).
- `assigned_user_id` (Optional[str]): ID of the assigned User record.
- `teams_ids` (Optional[List[str]]): Team IDs.
- `campaign_id` (Optional[str]): Campaign ID.
- `target_list_id` (Optional[str]): Target list ID.
- `duplicate_source_id` (Optional[str]): Record ID of an entity being duplicated. Sent as header `X-Duplicate-Source-Id`.
- `skip_duplicate_check` (Optional[bool]): Skip duplicate check flag. When provided, sent as header `X-Skip-Duplicate-Check` with value `'true'` or `'false'`.
- `custom_fields` (Optional[Dict[str, Any]]): A dictionary of EspoCRM custom fields to update on the Lead record. All EspoCRM custom fields are prefixed with `c`.

Example Requests:
- Create a basic lead with name and email:
espo_create_lead_tool(first_name="Jane", last_name="Doe", email_address="jane@example.com")
- Create a lead with multiple emails and phone numbers:
espo_create_lead_tool(first_name="Acme", last_name="Inc", email_address_data=[{"emailAddress": "a@acme.com", "primary": True}], phone_number_data=[{"phoneNumber": "+123456789", "primary": True}])
- Create a lead with a custom field (e.g., c_demo_url):
espo_create_lead_tool(first_name="Demo", last_name="User", custom_fields={"c_demo_url": "https://example.com/demo", "c_score": 90})

Returns:
- A structured dict containing the API response with keys:
`status_code`, `ok`, `data`, `error`, and `error_type`.

Remove an existing Lead record in EspoCRM.

Args:
- `lead_id` (str): The ID of the Lead to remove.

Example Request:
- espo_delete_lead_tool(lead_id="abc123")

Returns:
- A structured dict containing the API response with keys:
`status_code`, `ok`, `data`, `error`, and `error_type`.

List leads from EspoCRM with optional filtering, sorting, and pagination.

This tool fetches leads with advanced query options such as attribute selection, boolean filters,
pagination, sorting, and deep where group conditions.

Args:
- `attribute_select` (Optional[List[str]]): Attributes to include in the response to improve performance.
- `bool_filter_list` (Optional[List[str]]): Boolean filters such as `['onlyMy']`.
- `max_size` (Optional[int]): Maximum number of records to return (0–200). Overrides page_size if provided.
- `offset` (Optional[int]): Pagination offset (0-based). If not set, computed from page and page_size.
- `order` (Optional[str]): Sort direction, either `'asc'` or `'desc'`.
- `order_by` (Optional[str]): Attribute to sort results by.
- `primary_filter` (Optional[str]): Primary filter to use. Allowed: `'actual'`, `'active'`, `'converted'`.
- `text_filter` (Optional[str]): Text search query. Supports wildcard `*`.
- `where_group` (Optional[List[Dict[str, Any]]]): Advanced deepObject filters for complex queries.

Example Requests:
- Fetch first 50 leads with only selected attributes:
espo_list_leads_tool(attribute_select=["firstName", "lastName", "emailAddress"], max_size=50)
- Fetch leads assigned only to the current user, sorted by creation date descending:
espo_list_leads_tool(bool_filter_list=["onlyMy"], order="desc", order_by="createdAt")
- Fetch leads using advanced whereGroup filter:
espo_list_leads_tool(where_group=[{"type": "equals", "attribute": "status", "value": "New"}, {"type": "contains", "attribute": "emailAddress", "value": "@example.com"}])

Returns:
- A dictionary containing leads data and metadata.

Get a single Lead record by ID from EspoCRM.

Args:
- `lead_id` (str): The ID of the Lead to fetch.

Example Request:
- espo_get_lead_tool(lead_id="abc123")

Returns:
- A structured dict containing the API response with keys:
`status_code`, `ok`, `data`, `error`, and `error_type`.

Update an existing Lead in EspoCRM.

This tool updates a Lead record by `lead_id`. Provide any Lead fields to update.
parameters left as `None` will not be sent to avoid overwriting unchanged values.

Args:
- `lead_id` (str): ID of the Lead record to update.
- `salutation_name` (Optional[str]): Salutation (e.g. 'Mr.', 'Ms.', 'Dr.').
- `first_name` (Optional[str]): First name (<= 100 chars).
- `middle_name` (Optional[str]): Middle name (<= 100 chars).
- `last_name` (Optional[str]): Last name (<= 100 chars).
- `title` (Optional[str]): Job title (<= 100 chars).
- `status` (Optional[str]): Lead status (New, Assigned, In Process, Converted, Recycled, Dead).
- `source` (Optional[str]): Lead source (Call, Email, Campaign, etc.).
- `industry` (Optional[str]): Industry (see API allowed values).
- `opportunity_amount` (Optional[float]): Opportunity amount (>= 0).
- `opportunity_amount_currency` (Optional[str]): Currency code (USD, EUR).
- `website` (Optional[str]): Website (<= 255 chars).
- `address_street` (Optional[str]): Street (<= 255 chars).
- `address_city` (Optional[str]): City (<= 100 chars).
- `address_state` (Optional[str]): State (<= 100 chars).
- `address_country` (Optional[str]): Country (<= 100 chars).
- `address_postal_code` (Optional[str]): Postal code (<= 40 chars).
- `email_address` (Optional[str]): Primary email (<= 255 chars).
- `email_address_data` (Optional[List[Dict[str, Any]]]): Multiple email objects.
- `phone_number` (Optional[str]): Primary phone (<= 36 chars).
- `phone_number_data` (Optional[List[Dict[str, Any]]]): Multiple phone objects.
- `do_not_call` (Optional[bool]): Do not call flag.
- `description` (Optional[str]): Description / notes.
- `account_name` (Optional[str]): Account name (<= 255 chars).
- `assigned_user_id` (Optional[str]): ID of the assigned User record.
- `teams_ids` (Optional[List[str]]): Team IDs.
- `campaign_id` (Optional[str]): Campaign ID.
- `target_list_id` (Optional[str]): Target list ID.
- `custom_fields` (Optional[Dict[str, Any]]): A dictionary of EspoCRM custom fields to update on the Lead record. All EspoCRM custom fields are prefixed with `c`.

Example Requests:
- Update a lead's name and email:
espo_update_lead_tool(lead_id="abc123", first_name="Jane", last_name="Doe", email_address="jane@example.com")
- Update multiple fields including phone numbers:
espo_update_lead_tool(lead_id="abc123", phone_number_data=[{"phoneNumber": "+123456789", "primary": True}], do_not_call=True)
- Update custom fields:
espo_update_lead_tool(lead_id="6954254b5723b823f", custom_fields={"c_demo_url": "https://someurl", "c_score": 85})

Returns:
- A structured dict containing the API response with keys:
`status_code`, `ok`, `data`, `error`, and `error_type`.