From 4f525db7ab4150dc6c5b3324fa3b7458828f7f0e Mon Sep 17 00:00:00 2001
From: jake-valsamis <jake@codeocean.com>
Date: Fri, 29 Aug 2025 15:11:52 -0400
Subject: [PATCH] update query description in search APIs

---
 src/codeocean/capsule.py    | 33 ++++++++++++++++++++++++++++++++-
 src/codeocean/data_asset.py | 26 ++++++++++++++++++++++++--
 2 files changed, 56 insertions(+), 3 deletions(-)

diff --git a/src/codeocean/capsule.py b/src/codeocean/capsule.py
index 119afcc..c27545e 100644
--- a/src/codeocean/capsule.py
+++ b/src/codeocean/capsule.py
@@ -140,7 +140,38 @@ class CapsuleSearchParams:
     query: Optional[str] = dataclass_field(
         default=None,
         metadata={
-            "description": "Search query in free text or structured format (name:... tag:...)"
+            "description": """Search expression supporting free text and field:value filters.
+            Valid fields:
+             - id
+             - name
+             - doi
+             - tag
+             - field
+             - affiliation
+             - journal
+             - article
+             - author
+
+            Free text:
+             - Matches across weighted fields (name, tags, description, authors, etc.)
+
+            Syntax rules:
+             - Same field repeated = OR
+             - Different fields = AND
+             - Quotes = exact phrase
+             - No explicit OR operator
+             - No wildcards (*)
+             - Not case sensitive
+
+            Notes:
+             - "description" is not directly searchable; it is covered by free-text matching.
+
+            Examples:
+             - name:RNA-seq tag:genomics
+             - name:"single cell analysis"
+             - Synergy
+             - name:Synergy
+            """
         },
     )
     next_token: Optional[str] = dataclass_field(
diff --git a/src/codeocean/data_asset.py b/src/codeocean/data_asset.py
index 4e4ecd8..cfc28c9 100644
--- a/src/codeocean/data_asset.py
+++ b/src/codeocean/data_asset.py
@@ -538,8 +538,30 @@ class DataAssetSearchParams:
     query: Optional[str] = field(
         default=None,
         metadata={
-            "description": "Search query in free text or structured format "
-            "(name:... tag:... run_script:... commit_id:...)",
+            "description": """Search expression supporting free text and field:value filters.
+            Valid fields:
+             - name
+             - tag
+             - run_script
+             - commit_id
+             - contained_data_id
+
+            Free text:
+             - Matches across weighted fields (name, tags, description, custom metadata)
+
+            Syntax rules:
+             - Same field repeated = OR
+             - Different fields = AND
+             - Quotes = exact phrase
+             - No explicit OR operator
+             - No wildcards (*)
+             - Not case sensitive
+
+            Examples:
+             - name:RNA-seq tag:genomics
+             - name:"analysis pipeline"
+             - name:Synergy
+            """
         },
     )
     next_token: Optional[str] = field(