diff --git a/docs/tables/create.mdx b/docs/tables/create.mdx
index 0e422df..407b02b 100644
--- a/docs/tables/create.mdx
+++ b/docs/tables/create.mdx
@@ -419,6 +419,43 @@ If you forget the name of your table, you can always get a listing of all table
     </CodeBlock>
 </CodeGroup>
 
+### List tables in pages
+
+Python's `db.list_tables()` and the TypeScript `db.listTables()` method return one
+page of table names at a time, along with an opaque `pageToken` that resumes the
+listing. Use these when a database holds enough tables that a single response is
+not practical. The TypeScript `db.tableNames()` method still works but is
+deprecated in favor of `db.listTables()`.
+
+Treat the `pageToken` as opaque. Do not construct or parse it. A page can hold
+fewer entries than `limit` and still not be the last one, so keep going until
+the response no longer carries a `pageToken`.
+
+<Warning>
+`listTables` and `list_tables` return tables in an arbitrary, backend-defined
+order, not lexicographical order. If you need a stable alphabetical listing
+with `startAfter` semantics, use the deprecated `tableNames` in TypeScript or
+`table_names` in Rust, which retain that behavior.
+</Warning>
+
+Walk the pages until the response no longer carries a `pageToken`:
+
+```typescript TypeScript icon="square-js"
+const names: string[] = [];
+let pageToken: string | undefined = undefined;
+do {
+  const page = await db.listTables({ pageToken, limit: 100 });
+  names.push(...page.tables);
+  pageToken = page.pageToken;
+} while (pageToken);
+```
+
+To list tables inside a namespace, pass the namespace path first:
+
+```typescript TypeScript icon="square-js"
+const page = await db.listTables(["prod", "search"], { limit: 100 });
+```
+
 ## Drop a table
 
 Use the `drop_table()` method on the database to remove a table.