diff --git a/docs/src/js/classes/Table.md b/docs/src/js/classes/Table.md
index 5ff2265e9..b5ec104f4 100644
--- a/docs/src/js/classes/Table.md
+++ b/docs/src/js/classes/Table.md
@@ -1296,9 +1296,10 @@ The following keys are treated specially, by convention, and should be
 used when appropriate:
 
 - `lancedb:description`: for a human-readable description of a field.
-- `lancedb:tag:(tag_name)`: for a user-defined key-value tag.
-- `lancedb:logical_column`: for a column grouping; e.g. `feature_v1` and
-  `feature_v2` might be in the same logical_column.
+- `lancedb:tag:<name>`: for a user-defined key-value tag, where the suffix
+  names the tag category; e.g. `lancedb:tag:model: "clip"`.
+- `lancedb:logical-column`: for a column grouping; e.g. `feature_v1` and
+  `feature_v2` might be in the same logical column.
 - `lancedb:status`: for status options (`production`, `candidate`,
   `deprecated`, `archived`) to designate the current life cycle state of
   this column.
diff --git a/nodejs/lancedb/table.ts b/nodejs/lancedb/table.ts
index 71ee08ee5..23b39eda1 100644
--- a/nodejs/lancedb/table.ts
+++ b/nodejs/lancedb/table.ts
@@ -633,9 +633,10 @@ export abstract class Table {
    * used when appropriate:
    *
    * - `lancedb:description`: for a human-readable description of a field.
-   * - `lancedb:tag:(tag_name)`: for a user-defined key-value tag.
-   * - `lancedb:logical_column`: for a column grouping; e.g. `feature_v1` and
-   *   `feature_v2` might be in the same logical_column.
+   * - `lancedb:tag:<name>`: for a user-defined key-value tag, where the suffix
+   *   names the tag category; e.g. `lancedb:tag:model: "clip"`.
+   * - `lancedb:logical-column`: for a column grouping; e.g. `feature_v1` and
+   *   `feature_v2` might be in the same logical column.
    * - `lancedb:status`: for status options (`production`, `candidate`,
    *   `deprecated`, `archived`) to designate the current life cycle state of
    *   this column.
diff --git a/python/python/lancedb/table.py b/python/python/lancedb/table.py
index ced2d55ef..51cfadfd7 100644
--- a/python/python/lancedb/table.py
+++ b/python/python/lancedb/table.py
@@ -2131,9 +2131,10 @@ class Table(ABC):
             be used when appropriate:
 
             - "lancedb:description": for a human-readable description of a field.
-            - "lancedb:tag:(tag_name)" for a user-defined key-value tag.
-            - "lancedb:logical_column" for a column grouping; e.g. "feature_v1"
-                and "feature_v2" might be in the same logical_column.
+            - ``"lancedb:tag:<name>"`` for a user-defined key-value tag, where the
+                suffix names the tag category; e.g. "lancedb:tag:model": "clip".
+            - "lancedb:logical-column" for a column grouping; e.g. "feature_v1"
+                and "feature_v2" might be in the same logical column.
             - "lancedb:status" for status options ("production", "candidate",
                 "deprecated", "archived") to designate the current life cycle
                 state of this column.
diff --git a/rust/lancedb/src/table.rs b/rust/lancedb/src/table.rs
index e44a78515..026aeb6e5 100644
--- a/rust/lancedb/src/table.rs
+++ b/rust/lancedb/src/table.rs
@@ -1762,9 +1762,10 @@ impl Table {
     /// used when appropriate:
     ///
     /// - `lancedb:description`: for a human-readable description of a field.
-    /// - `lancedb:tag:(tag_name)`: for a user-defined key-value tag.
-    /// - `lancedb:logical_column`: for a column grouping; e.g. `feature_v1` and
-    ///   `feature_v2` might be in the same logical_column.
+    /// - `lancedb:tag:<name>`: for a user-defined key-value tag, where the suffix
+    ///   names the tag category; e.g. `lancedb:tag:model: "clip"`.
+    /// - `lancedb:logical-column`: for a column grouping; e.g. `feature_v1` and
+    ///   `feature_v2` might be in the same logical column.
     /// - `lancedb:status`: for status options (`production`, `candidate`,
     ///   `deprecated`, `archived`) to designate the current life cycle state of
     ///   this column.