airbyte-agent-zendesk-support 0.18.58__tar.gz → 0.18.61__tar.gz

{airbyte_agent_zendesk_support-0.18.58 → airbyte_agent_zendesk_support-0.18.61}/AUTH.md

@@ -103,7 +103,7 @@ connector = ZendeskSupportConnector(
 )
 
 @agent.tool_plain # assumes you're using Pydantic AI
-@ZendeskSupportConnector.describe
+@ZendeskSupportConnector.tool_utils
 async def zendesk-support_execute(entity: str, action: str, params: dict | None = None):
     return await connector.execute(entity, action, params or {})
 ```

{airbyte_agent_zendesk_support-0.18.58 → airbyte_agent_zendesk_support-0.18.61}/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Zendesk Support changelog
 
+## [0.18.61] - 2026-01-24
+- Updated connector definition (YAML version 0.1.8)
+- Source commit: 609c1d86
+- SDK version: 0.1.0
+
+## [0.18.60] - 2026-01-23
+- Updated connector definition (YAML version 0.1.8)
+- Source commit: 592446b8
+- SDK version: 0.1.0
+
+## [0.18.59] - 2026-01-23
+- Updated connector definition (YAML version 0.1.7)
+- Source commit: 416466da
+- SDK version: 0.1.0
+
 ## [0.18.58] - 2026-01-23
 - Updated connector definition (YAML version 0.1.7)
 - Source commit: f17cdd8c

{airbyte_agent_zendesk_support-0.18.58 → airbyte_agent_zendesk_support-0.18.61}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: airbyte-agent-zendesk-support
-Version: 0.18.58
+Version: 0.18.61
 Summary: Airbyte Zendesk-Support Connector for AI platforms
 Project-URL: Homepage, https://github.com/airbytehq/airbyte-agent-connectors
 Project-URL: Documentation, https://docs.airbyte.com/ai-agents/
@@ -89,7 +89,7 @@ connector = ZendeskSupportConnector(
 )
 
 @agent.tool_plain # assumes you're using Pydantic AI
-@ZendeskSupportConnector.describe
+@ZendeskSupportConnector.tool_utils
 async def zendesk-support_execute(entity: str, action: str, params: dict | None = None):
     return await connector.execute(entity, action, params or {})
 ```
@@ -110,11 +110,12 @@ connector = ZendeskSupportConnector(
 )
 
 @agent.tool_plain # assumes you're using Pydantic AI
-@ZendeskSupportConnector.describe
+@ZendeskSupportConnector.tool_utils
 async def zendesk-support_execute(entity: str, action: str, params: dict | None = None):
     return await connector.execute(entity, action, params or {})
 ```
 
+
 ## Full documentation
 
 This connector supports the following entities and actions.
@@ -153,6 +154,6 @@ For the service's official API docs, see the [Zendesk-Support API reference](htt
 
 ## Version information
 
-- **Package version:** 0.18.58
-- **Connector version:** 0.1.7
-- **Generated with Connector SDK commit SHA:** f17cdd8c92950751a75daff9c6bf74df05774ede
+- **Package version:** 0.18.61
+- **Connector version:** 0.1.8
+- **Generated with Connector SDK commit SHA:** 609c1d86c76b36ff699b57123a5a8c2050d958c3

{airbyte_agent_zendesk_support-0.18.58 → airbyte_agent_zendesk_support-0.18.61}/README.md

@@ -56,7 +56,7 @@ connector = ZendeskSupportConnector(
 )
 
 @agent.tool_plain # assumes you're using Pydantic AI
-@ZendeskSupportConnector.describe
+@ZendeskSupportConnector.tool_utils
 async def zendesk-support_execute(entity: str, action: str, params: dict | None = None):
     return await connector.execute(entity, action, params or {})
 ```
@@ -77,11 +77,12 @@ connector = ZendeskSupportConnector(
 )
 
 @agent.tool_plain # assumes you're using Pydantic AI
-@ZendeskSupportConnector.describe
+@ZendeskSupportConnector.tool_utils
 async def zendesk-support_execute(entity: str, action: str, params: dict | None = None):
     return await connector.execute(entity, action, params or {})
 ```
 
+
 ## Full documentation
 
 This connector supports the following entities and actions.
@@ -120,6 +121,6 @@ For the service's official API docs, see the [Zendesk-Support API reference](htt
 
 ## Version information
 
-- **Package version:** 0.18.58
-- **Connector version:** 0.1.7
-- **Generated with Connector SDK commit SHA:** f17cdd8c92950751a75daff9c6bf74df05774ede
+- **Package version:** 0.18.61
+- **Connector version:** 0.1.8
+- **Generated with Connector SDK commit SHA:** 609c1d86c76b36ff699b57123a5a8c2050d958c3

{airbyte_agent_zendesk_support-0.18.58 → airbyte_agent_zendesk_support-0.18.61}/REFERENCE.md

@@ -258,7 +258,7 @@ curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_i
 | `created_at` | `string` | Timestamp indicating when the ticket was created |
 | `custom_fields` | `array` | Array of custom field values specific to the account's ticket configuration |
 | `custom_status_id` | `integer` | Unique identifier of the custom status applied to the ticket |
-| `deleted_ticket_form_id` | `integer` | Unique identifier of the ticket form if it was deleted after the ticket was created |
+| `deleted_ticket_form_id` | `integer` | The ID of the ticket form that was previously associated with this ticket but has since been deleted |
 | `description` | `string` | Initial description or content of the ticket when it was created |
 | `due_at` | `string` | Timestamp indicating when the ticket is due for completion or resolution |
 | `email_cc_ids` | `array` | Array of user identifiers who are CC'd on ticket email notifications |
@@ -268,7 +268,7 @@ curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_i
 | `followup_ids` | `array` | Array of identifiers for follow-up tickets related to this ticket |
 | `forum_topic_id` | `integer` | Unique identifier linking the ticket to a forum topic if applicable |
 | `from_messaging_channel` | `boolean` | Boolean indicating whether the ticket originated from a messaging channel |
-| `generated_timestamp` | `integer` | Timestamp updated for all ticket updates including system changes, used for incremental export co... |
+| `generated_timestamp` | `integer` | Timestamp updated for all ticket updates including system changes, used for incremental export |
 | `group_id` | `integer` | Unique identifier of the agent group assigned to handle the ticket |
 | `has_incidents` | `boolean` | Boolean indicating whether this problem ticket has related incident tickets |
 | `id` | `integer` | Unique identifier for the ticket |
@@ -308,7 +308,7 @@ curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_i
 | `hits[].data.created_at` | `string` | Timestamp indicating when the ticket was created |
 | `hits[].data.custom_fields` | `array` | Array of custom field values specific to the account's ticket configuration |
 | `hits[].data.custom_status_id` | `integer` | Unique identifier of the custom status applied to the ticket |
-| `hits[].data.deleted_ticket_form_id` | `integer` | Unique identifier of the ticket form if it was deleted after the ticket was created |
+| `hits[].data.deleted_ticket_form_id` | `integer` | The ID of the ticket form that was previously associated with this ticket but has since been deleted |
 | `hits[].data.description` | `string` | Initial description or content of the ticket when it was created |
 | `hits[].data.due_at` | `string` | Timestamp indicating when the ticket is due for completion or resolution |
 | `hits[].data.email_cc_ids` | `array` | Array of user identifiers who are CC'd on ticket email notifications |
@@ -318,7 +318,7 @@ curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_i
 | `hits[].data.followup_ids` | `array` | Array of identifiers for follow-up tickets related to this ticket |
 | `hits[].data.forum_topic_id` | `integer` | Unique identifier linking the ticket to a forum topic if applicable |
 | `hits[].data.from_messaging_channel` | `boolean` | Boolean indicating whether the ticket originated from a messaging channel |
-| `hits[].data.generated_timestamp` | `integer` | Timestamp updated for all ticket updates including system changes, used for incremental export co... |
+| `hits[].data.generated_timestamp` | `integer` | Timestamp updated for all ticket updates including system changes, used for incremental export |
 | `hits[].data.group_id` | `integer` | Unique identifier of the agent group assigned to handle the ticket |
 | `hits[].data.has_incidents` | `boolean` | Boolean indicating whether this problem ticket has related incident tickets |
 | `hits[].data.id` | `integer` | Unique identifier for the ticket |
@@ -1894,9 +1894,9 @@ curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_i
 |------------|------|-------------|
 | `active` | `boolean` | Whether this field is currently available for use |
 | `agent_description` | `string` | A description of the ticket field that only agents can see |
-| `collapsed_for_agents` | `boolean` | If true, the field is shown to agents by default; if false, it is hidden alongside infrequently u... |
+| `collapsed_for_agents` | `boolean` | If true, the field is shown to agents by default; if false, it is hidden alongside infrequently used fields |
 | `created_at` | `string` | Timestamp when the custom ticket field was created |
-| `custom_field_options` | `array` | Array of option objects for custom ticket fields of type multiselect or tagger, containing name a... |
+| `custom_field_options` | `array` | Array of option objects for custom ticket fields of type multiselect or tagger |
 | `custom_statuses` | `array` | List of customized ticket statuses, only present for system ticket fields of type custom_status |
 | `description` | `string` | Text describing the purpose of the ticket field to users |
 | `editable_in_portal` | `boolean` | Whether this field is editable by end users in Help Center |
@@ -1915,7 +1915,7 @@ curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_i
 | `tag` | `string` | For checkbox fields only, a tag added to tickets when the checkbox field is selected |
 | `title` | `string` | The title of the ticket field displayed to agents |
 | `title_in_portal` | `string` | The title of the ticket field displayed to end users in Help Center |
-| `type` | `string` | Field type such as text, textarea, checkbox, date, integer, decimal, regexp, multiselect, tagger,... |
+| `type` | `string` | Field type such as text, textarea, checkbox, date, integer, decimal, regexp, multiselect, or tagger |
 | `updated_at` | `string` | Timestamp when the custom ticket field was last updated |
 | `url` | `string` | The API URL for this ticket field resource |
 | `visible_in_portal` | `boolean` | Whether this field is visible to end users in Help Center |
@@ -1931,9 +1931,9 @@ curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_i
 | `hits[].data` | `object` | Record data containing the searchable fields listed above |
 | `hits[].data.active` | `boolean` | Whether this field is currently available for use |
 | `hits[].data.agent_description` | `string` | A description of the ticket field that only agents can see |
-| `hits[].data.collapsed_for_agents` | `boolean` | If true, the field is shown to agents by default; if false, it is hidden alongside infrequently u... |
+| `hits[].data.collapsed_for_agents` | `boolean` | If true, the field is shown to agents by default; if false, it is hidden alongside infrequently used fields |
 | `hits[].data.created_at` | `string` | Timestamp when the custom ticket field was created |
-| `hits[].data.custom_field_options` | `array` | Array of option objects for custom ticket fields of type multiselect or tagger, containing name a... |
+| `hits[].data.custom_field_options` | `array` | Array of option objects for custom ticket fields of type multiselect or tagger |
 | `hits[].data.custom_statuses` | `array` | List of customized ticket statuses, only present for system ticket fields of type custom_status |
 | `hits[].data.description` | `string` | Text describing the purpose of the ticket field to users |
 | `hits[].data.editable_in_portal` | `boolean` | Whether this field is editable by end users in Help Center |
@@ -1952,7 +1952,7 @@ curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_i
 | `hits[].data.tag` | `string` | For checkbox fields only, a tag added to tickets when the checkbox field is selected |
 | `hits[].data.title` | `string` | The title of the ticket field displayed to agents |
 | `hits[].data.title_in_portal` | `string` | The title of the ticket field displayed to end users in Help Center |
-| `hits[].data.type` | `string` | Field type such as text, textarea, checkbox, date, integer, decimal, regexp, multiselect, tagger,... |
+| `hits[].data.type` | `string` | Field type such as text, textarea, checkbox, date, integer, decimal, regexp, multiselect, or tagger |
 | `hits[].data.updated_at` | `string` | Timestamp when the custom ticket field was last updated |
 | `hits[].data.url` | `string` | The API URL for this ticket field resource |
 | `hits[].data.visible_in_portal` | `boolean` | Whether this field is visible to end users in Help Center |
@@ -2962,7 +2962,7 @@ curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_i
 | `group_id` | `integer` | The identifier of the group assigned to the ticket at the time the rating was submitted |
 | `id` | `integer` | Unique identifier for the satisfaction rating, automatically assigned upon creation |
 | `reason` | `string` | Free-text reason for a bad rating provided by the requester in a follow-up question |
-| `reason_id` | `integer` | Identifier for the predefined reason given for a negative rating, only applicable when score is '... |
+| `reason_id` | `integer` | Identifier for the predefined reason given for a negative rating |
 | `requester_id` | `integer` | The identifier of the ticket requester who submitted the satisfaction rating |
 | `score` | `string` | The satisfaction rating value: 'offered', 'unoffered', 'good', or 'bad' |
 | `ticket_id` | `integer` | The identifier of the ticket being rated |
@@ -2984,7 +2984,7 @@ curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_i
 | `hits[].data.group_id` | `integer` | The identifier of the group assigned to the ticket at the time the rating was submitted |
 | `hits[].data.id` | `integer` | Unique identifier for the satisfaction rating, automatically assigned upon creation |
 | `hits[].data.reason` | `string` | Free-text reason for a bad rating provided by the requester in a follow-up question |
-| `hits[].data.reason_id` | `integer` | Identifier for the predefined reason given for a negative rating, only applicable when score is '... |
+| `hits[].data.reason_id` | `integer` | Identifier for the predefined reason given for a negative rating |
 | `hits[].data.requester_id` | `integer` | The identifier of the ticket requester who submitted the satisfaction rating |
 | `hits[].data.score` | `string` | The satisfaction rating value: 'offered', 'unoffered', 'good', or 'bad' |
 | `hits[].data.ticket_id` | `integer` | The identifier of the ticket being rated |
@@ -3417,7 +3417,7 @@ curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_i
 | `raw_display_name` | `string` | The dynamic content placeholder if present, or the display_name value if not |
 | `raw_name` | `string` | The dynamic content placeholder if present, or the name value if not |
 | `restricted_brand_ids` | `array` | IDs of all brands that this ticket form is restricted to |
-| `ticket_field_ids` | `array` | IDs of all ticket fields included in this ticket form, ordered to determine field display sequenc... |
+| `ticket_field_ids` | `array` | IDs of all ticket fields included in this ticket form |
 | `updated_at` | `string` | Timestamp of the last update to the ticket form |
 | `url` | `string` | URL of the ticket form |
 
@@ -3444,7 +3444,7 @@ curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_i
 | `hits[].data.raw_display_name` | `string` | The dynamic content placeholder if present, or the display_name value if not |
 | `hits[].data.raw_name` | `string` | The dynamic content placeholder if present, or the name value if not |
 | `hits[].data.restricted_brand_ids` | `array` | IDs of all brands that this ticket form is restricted to |
-| `hits[].data.ticket_field_ids` | `array` | IDs of all ticket fields included in this ticket form, ordered to determine field display sequenc... |
+| `hits[].data.ticket_field_ids` | `array` | IDs of all ticket fields included in this ticket form |
 | `hits[].data.updated_at` | `string` | Timestamp of the last update to the ticket form |
 | `hits[].data.url` | `string` | URL of the ticket form |
 | `next_cursor` | `string \| null` | Cursor for next page of results |
@@ -3748,3 +3748,4 @@ curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_i
 | `range_header` | `string` | No | Optional Range header for partial downloads (e.g., 'bytes=0-99') |
 
 
+

{airbyte_agent_zendesk_support-0.18.58 → airbyte_agent_zendesk_support-0.18.61}/airbyte_agent_zendesk_support/_vendored/connector_sdk/connector_model_loader.py

@@ -145,6 +145,87 @@ def _deproxy_schema(obj: Any) -> Any:
         return obj
 
 
+def _type_includes(type_value: Any, target: str) -> bool:
+    if isinstance(type_value, list):
+        return target in type_value
+    return type_value == target
+
+
+def _flatten_cache_properties(properties: dict[str, Any], prefix: str) -> list[str]:
+    entries: list[str] = []
+    for prop_name, prop in properties.items():
+        path = f"{prefix}{prop_name}" if prefix else prop_name
+        entries.append(path)
+
+        prop_type = getattr(prop, "type", None) if not isinstance(prop, dict) else prop.get("type")
+        prop_properties = getattr(prop, "properties", None) if not isinstance(prop, dict) else prop.get("properties")
+
+        if _type_includes(prop_type, "array"):
+            array_path = f"{path}[]"
+            entries.append(array_path)
+            if isinstance(prop_properties, dict):
+                entries.extend(_flatten_cache_properties(prop_properties, prefix=f"{array_path}."))
+        elif isinstance(prop_properties, dict):
+            entries.extend(_flatten_cache_properties(prop_properties, prefix=f"{path}."))
+
+    return entries
+
+
+def _flatten_cache_field_paths(field: Any) -> list[str]:
+    field_name = getattr(field, "name", None) if not isinstance(field, dict) else field.get("name")
+    if not isinstance(field_name, str) or not field_name:
+        return []
+
+    field_type = getattr(field, "type", None) if not isinstance(field, dict) else field.get("type")
+    field_properties = getattr(field, "properties", None) if not isinstance(field, dict) else field.get("properties")
+
+    entries = [field_name]
+    if _type_includes(field_type, "array"):
+        array_path = f"{field_name}[]"
+        entries.append(array_path)
+        if isinstance(field_properties, dict):
+            entries.extend(_flatten_cache_properties(field_properties, prefix=f"{array_path}."))
+    elif isinstance(field_properties, dict):
+        entries.extend(_flatten_cache_properties(field_properties, prefix=f"{field_name}."))
+
+    return entries
+
+
+def _dedupe_strings(values: list[str]) -> list[str]:
+    seen: set[str] = set()
+    ordered: list[str] = []
+    for value in values:
+        if value not in seen:
+            seen.add(value)
+            ordered.append(value)
+    return ordered
+
+
+def _extract_search_field_paths(spec: OpenAPIConnector) -> dict[str, list[str]]:
+    cache_config = getattr(spec.info, "x_airbyte_cache", None)
+    entities = getattr(cache_config, "entities", None)
+    if not isinstance(entities, list):
+        return {}
+
+    search_fields: dict[str, list[str]] = {}
+    for entity in entities:
+        entity_name = getattr(entity, "entity", None) if not isinstance(entity, dict) else entity.get("entity")
+        if not isinstance(entity_name, str) or not entity_name:
+            continue
+
+        fields = getattr(entity, "fields", None) if not isinstance(entity, dict) else entity.get("fields")
+        if not isinstance(fields, list):
+            continue
+
+        field_paths: list[str] = []
+        for field in fields:
+            field_paths.extend(_flatten_cache_field_paths(field))
+
+        search_fields[entity_name] = _dedupe_strings(field_paths)
+
+    return search_fields
+
+
 def parse_openapi_spec(raw_config: dict) -> OpenAPIConnector:
     """Parse OpenAPI specification from YAML.
 
@@ -434,6 +515,8 @@ def convert_openapi_to_connector_model(spec: OpenAPIConnector) -> ConnectorModel
     if not connector_id:
         raise InvalidOpenAPIError("Missing required x-airbyte-connector-id field")
 
+    search_field_paths = _extract_search_field_paths(spec)
+
     # Create ConnectorModel
     model = ConnectorModel(
         id=connector_id,
@@ -444,6 +527,7 @@ def convert_openapi_to_connector_model(spec: OpenAPIConnector) -> ConnectorModel
         entities=entities,
         openapi_spec=spec,
         retry_config=retry_config,
+        search_field_paths=search_field_paths,
     )
 
     return model

{airbyte_agent_zendesk_support-0.18.58 → airbyte_agent_zendesk_support-0.18.61}/airbyte_agent_zendesk_support/_vendored/connector_sdk/executor/local_executor.py

@@ -1032,7 +1032,9 @@ class LocalExecutor:
         if "variables" in graphql_config and graphql_config["variables"]:
             variables = self._interpolate_variables(graphql_config["variables"], params, param_defaults)
             # Filter out None values (optional fields not provided) - matches REST _extract_body() behavior
-            body["variables"] = {k: v for k, v in variables.items() if v is not None}
+            # But preserve None for variables explicitly marked as nullable (e.g., to unassign a user)
+            nullable_vars = set(graphql_config.get("x-airbyte-nullable-variables") or [])
+            body["variables"] = {k: v for k, v in variables.items() if v is not None or k in nullable_vars}
 
         # Add operation name if specified
         if "operationName" in graphql_config:

{airbyte_agent_zendesk_support-0.18.58 → airbyte_agent_zendesk_support-0.18.61}/airbyte_agent_zendesk_support/_vendored/connector_sdk/introspection.py

@@ -18,6 +18,185 @@ from typing import Any, Protocol
 MAX_EXAMPLE_QUESTIONS = 5  # Maximum number of example questions to include in description
 
 
+def _type_includes(type_value: Any, target: str) -> bool:
+    if isinstance(type_value, list):
+        return target in type_value
+    return type_value == target
+
+
+def _is_object_schema(schema: dict[str, Any]) -> bool:
+    if "properties" in schema:
+        return True
+    return _type_includes(schema.get("type"), "object")
+
+
+def _is_array_schema(schema: dict[str, Any]) -> bool:
+    if "items" in schema:
+        return True
+    return _type_includes(schema.get("type"), "array")
+
+
+def _dedupe_param_entries(entries: list[tuple[str, bool]]) -> list[tuple[str, bool]]:
+    seen: dict[str, bool] = {}
+    ordered: list[str] = []
+    for name, required in entries:
+        if name not in seen:
+            seen[name] = required
+            ordered.append(name)
+        else:
+            seen[name] = seen[name] or required
+    return [(name, seen[name]) for name in ordered]
+
+
+def _flatten_schema_params(
+    schema: dict[str, Any],
+    prefix: str = "",
+    parent_required: bool = True,
+    seen_stack: set[int] | None = None,
+) -> list[tuple[str, bool]]:
+    if not isinstance(schema, dict):
+        return []
+
+    if seen_stack is None:
+        seen_stack = set()
+
+    schema_id = id(schema)
+    if schema_id in seen_stack:
+        return []
+
+    seen_stack.add(schema_id)
+    try:
+        entries: list[tuple[str, bool]] = []
+
+        for subschema in schema.get("allOf", []) or []:
+            if isinstance(subschema, dict):
+                entries.extend(_flatten_schema_params(subschema, prefix, parent_required, seen_stack))
+
+        for keyword in ("anyOf", "oneOf"):
+            for subschema in schema.get(keyword, []) or []:
+                if isinstance(subschema, dict):
+                    entries.extend(_flatten_schema_params(subschema, prefix, False, seen_stack))
+
+        properties = schema.get("properties")
+        if isinstance(properties, dict):
+            required_fields = set(schema.get("required", [])) if isinstance(schema.get("required"), list) else set()
+            for prop_name, prop_schema in properties.items():
+                path = f"{prefix}{prop_name}" if prefix else prop_name
+                is_required = parent_required and prop_name in required_fields
+                entries.append((path, is_required))
+
+                if isinstance(prop_schema, dict):
+                    if _is_array_schema(prop_schema):
+                        array_path = f"{path}[]"
+                        entries.append((array_path, is_required))
+                        items = prop_schema.get("items")
+                        if isinstance(items, dict):
+                            entries.extend(_flatten_schema_params(items, prefix=f"{array_path}.", parent_required=is_required, seen_stack=seen_stack))
+                    if _is_object_schema(prop_schema):
+                        entries.extend(_flatten_schema_params(prop_schema, prefix=f"{path}.", parent_required=is_required, seen_stack=seen_stack))
+
+        return _dedupe_param_entries(entries)
+    finally:
+        seen_stack.remove(schema_id)
+
+
+def _cache_field_value(field: Any, key: str) -> Any:
+    if isinstance(field, dict):
+        return field.get(key)
+    return getattr(field, key, None)
+
+
+def _flatten_cache_properties(properties: dict[str, Any], prefix: str) -> list[str]:
+    entries: list[str] = []
+    for prop_name, prop in properties.items():
+        path = f"{prefix}{prop_name}" if prefix else prop_name
+        entries.append(path)
+
+        prop_type = _cache_field_value(prop, "type")
+        prop_properties = _cache_field_value(prop, "properties")
+
+        if _type_includes(prop_type, "array"):
+            array_path = f"{path}[]"
+            entries.append(array_path)
+            if isinstance(prop_properties, dict):
+                entries.extend(_flatten_cache_properties(prop_properties, prefix=f"{array_path}."))
+        elif isinstance(prop_properties, dict):
+            entries.extend(_flatten_cache_properties(prop_properties, prefix=f"{path}."))
+
+    return entries
+
+
+def _flatten_cache_field_paths(field: Any) -> list[str]:
+    field_name = _cache_field_value(field, "name")
+    if not isinstance(field_name, str) or not field_name:
+        return []
+
+    field_type = _cache_field_value(field, "type")
+    field_properties = _cache_field_value(field, "properties")
+
+    entries = [field_name]
+    if _type_includes(field_type, "array"):
+        array_path = f"{field_name}[]"
+        entries.append(array_path)
+        if isinstance(field_properties, dict):
+            entries.extend(_flatten_cache_properties(field_properties, prefix=f"{array_path}."))
+    elif isinstance(field_properties, dict):
+        entries.extend(_flatten_cache_properties(field_properties, prefix=f"{field_name}."))
+
+    return entries
+
+
+def _dedupe_strings(values: list[str]) -> list[str]:
+    seen: set[str] = set()
+    ordered: list[str] = []
+    for value in values:
+        if value not in seen:
+            seen.add(value)
+            ordered.append(value)
+    return ordered
+
+
+def _collect_search_field_paths(model: ConnectorModelProtocol) -> dict[str, list[str]]:
+    search_field_paths = getattr(model, "search_field_paths", None)
+    if isinstance(search_field_paths, dict) and search_field_paths:
+        normalized: dict[str, list[str]] = {}
+        for entity, fields in search_field_paths.items():
+            if not isinstance(entity, str) or not entity:
+                continue
+            if isinstance(fields, list):
+                normalized[entity] = _dedupe_strings([field for field in fields if isinstance(field, str) and field])
+        return normalized
+
+    openapi_spec = getattr(model, "openapi_spec", None)
+    info = getattr(openapi_spec, "info", None)
+    cache_config = getattr(info, "x_airbyte_cache", None)
+    entities = getattr(cache_config, "entities", None)
+    if not isinstance(entities, list):
+        return {}
+
+    search_fields: dict[str, list[str]] = {}
+    for entity in entities:
+        entity_name = _cache_field_value(entity, "entity")
+        if not isinstance(entity_name, str) or not entity_name:
+            continue
+
+        fields = _cache_field_value(entity, "fields") or []
+        if not isinstance(fields, list):
+            continue
+        field_paths: list[str] = []
+        for field in fields:
+            field_paths.extend(_flatten_cache_field_paths(field))
+
+        search_fields[entity_name] = _dedupe_strings(field_paths)
+
+    return search_fields
+
+
+def _format_search_param_signature() -> str:
+    params = ["query*", "limit?", "cursor?", "fields?"]
+    return f"({', '.join(params)})"
+
+
 class EndpointProtocol(Protocol):
     """Protocol defining the expected interface for endpoint parameters.
 
@@ -54,6 +233,9 @@ class ConnectorModelProtocol(Protocol):
     @property
     def openapi_spec(self) -> Any: ...
 
+    @property
+    def search_field_paths(self) -> dict[str, list[str]] | None: ...
+
 
 def format_param_signature(endpoint: EndpointProtocol) -> str:
     """Format parameter signature for an endpoint action.
@@ -86,9 +268,12 @@ def format_param_signature(endpoint: EndpointProtocol) -> str:
         required = schema.get("required", False)
         params.append(f"{name}{'*' if required else '?'}")
 
-    # Body fields
-    if request_schema:
-        required_fields = set(request_schema.get("required", []))
+    # Body fields (include nested params from schema when available)
+    if isinstance(request_schema, dict):
+        for name, required in _flatten_schema_params(request_schema):
+            params.append(f"{name}{'*' if required else '?'}")
+    elif request_schema:
+        required_fields = set(request_schema.get("required", [])) if isinstance(request_schema, dict) else set()
         for name in body_fields:
             params.append(f"{name}{'*' if name in required_fields else '?'}")
 
@@ -99,7 +284,7 @@ def describe_entities(model: ConnectorModelProtocol) -> list[dict[str, Any]]:
     """Generate entity descriptions from ConnectorModel.
 
     Returns a list of entity descriptions with detailed parameter information
-    for each action. This is used by generated connectors' describe() method.
+    for each action. This is used by generated connectors' list_entities() method.
 
     Args:
         model: Object conforming to ConnectorModelProtocol (e.g., ConnectorModel)
@@ -203,8 +388,8 @@ def generate_tool_description(model: ConnectorModelProtocol) -> str:
     - Response structure documentation with pagination hints
     - Example questions if available in the OpenAPI spec
 
-    This is used by the Connector.describe class method decorator to populate
-    function docstrings for AI framework integration.
+    This is used by the Connector.tool_utils decorator to populate function
+    docstrings for AI framework integration.
 
     Args:
         model: Object conforming to ConnectorModelProtocol (e.g., ConnectorModel)
@@ -213,8 +398,11 @@ def generate_tool_description(model: ConnectorModelProtocol) -> str:
         Formatted description string suitable for AI tool documentation
     """
     lines = []
+    # NOTE: Do not insert blank lines in the docstring; pydantic-ai parsing truncates
+    # at the first empty line and only keeps the initial section.
 
     # Entity/action parameter details (including pagination params like limit, starting_after)
+    search_field_paths = _collect_search_field_paths(model)
     lines.append("ENTITIES AND PARAMETERS:")
     for entity in model.entities:
         lines.append(f"  {entity.name}:")
@@ -228,14 +416,41 @@ def generate_tool_description(model: ConnectorModelProtocol) -> str:
                 lines.append(f"    - {action_str}{param_sig}")
             else:
                 lines.append(f"    - {action_str}()")
+        if entity.name in search_field_paths:
+            search_sig = _format_search_param_signature()
+            lines.append(f"    - search{search_sig}")
 
     # Response structure (brief, includes pagination hint)
-    lines.append("")
     lines.append("RESPONSE STRUCTURE:")
     lines.append("  - list/api_search: {data: [...], meta: {has_more: bool}}")
     lines.append("  - get: Returns entity directly (no envelope)")
     lines.append("  To paginate: pass starting_after=<last_id> while has_more is true")
 
+    lines.append("GUIDELINES:")
+    lines.append('  - Prefer cached search over direct API calls when using execute(): action="search" whenever possible.')
+    lines.append("  - Direct API actions (list/get/download) are slower and should be used only if search cannot answer the query.")
+    lines.append("  - Keep results small: use params.fields, params.query.filter, small params.limit, and cursor pagination.")
+    lines.append("  - If output is too large, refine the query with tighter filters/fields/limit.")
+
+    if search_field_paths:
+        lines.append("SEARCH (PREFERRED):")
+        lines.append('  execute(entity, action="search", params={')
+        lines.append('    "query": {"filter": <condition>, "sort": [{"field": "asc|desc"}, ...]},')
+        lines.append('    "limit": <int>, "cursor": <str>, "fields": ["field", "nested.field", ...]')
+        lines.append("  })")
+        lines.append('  Example: {"query": {"filter": {"eq": {"title": "Intro to Airbyte | Miinto"}}}, "limit": 1,')
+        lines.append('            "fields": ["id", "title", "started", "primaryUserId"]}')
+        lines.append("  Conditions are composable:")
+        lines.append("    - eq, neq, gt, gte, lt, lte, in, like, fuzzy, keyword, contains, any")
+        lines.append('    - and/or/not to combine conditions (e.g., {"and": [cond1, cond2]})')
+
+        lines.append("SEARCHABLE FIELDS:")
+        for entity_name, field_paths in search_field_paths.items():
+            if field_paths:
+                lines.append(f"  {entity_name}: {', '.join(field_paths)}")
+            else:
+                lines.append(f"  {entity_name}: (no fields listed)")
+
     # Add example questions if available in openapi_spec
     openapi_spec = getattr(model, "openapi_spec", None)
     if openapi_spec:
@@ -245,18 +460,15 @@ def generate_tool_description(model: ConnectorModelProtocol) -> str:
             if example_questions:
                 supported = getattr(example_questions, "supported", None)
                 if supported:
-                    lines.append("")
                     lines.append("EXAMPLE QUESTIONS:")
                     for q in supported[:MAX_EXAMPLE_QUESTIONS]:
                         lines.append(f"  - {q}")
 
     # Generic parameter description for function signature
-    lines.append("")
     lines.append("FUNCTION PARAMETERS:")
     lines.append("  - entity: Entity name (string)")
     lines.append("  - action: Operation to perform (string)")
     lines.append("  - params: Operation parameters (dict) - see entity details above")
-    lines.append("")
     lines.append("Parameter markers: * = required, ? = optional")
 
     return "\n".join(lines)