diff --git a/src/memos/api/product_models.py b/src/memos/api/product_models.py
index 049ca544a..d2334bdcf 100644
--- a/src/memos/api/product_models.py
+++ b/src/memos/api/product_models.py
@@ -400,18 +400,15 @@ class APISearchRequest(BaseRequest):
     )
 
     # ==== Filter conditions ====
-    # TODO: maybe add detailed description later
     filter: dict[str, Any] | None = Field(
         None,
-        description="""
-        Filter for the memory, example:
-        {
-            "`and` or `or`": [
-                {"id": "uuid-xxx"},
-                {"created_at": {"gt": "2024-01-01"}},
-            ]
-        }
-        """,
+        description=(
+            "Optional structured metadata filter for narrowing memory search results. "
+            "Supports logical operators such as `and` and `or`, plus field-level "
+            "operator objects. Example: "
+            '`{"and": [{"field_name": {"eq": "value"}}, {"other_field": {"gte": 10}}]}`. '
+            "None means no metadata filter is applied."
+        ),
     )
 
     # ==== Extended capabilities ====