diff --git a/.release-please-manifest.json b/.release-please-manifest.json
index 3107bf4b..1e8c1322 100644
--- a/.release-please-manifest.json
+++ b/.release-please-manifest.json
@@ -1,3 +1,3 @@
 {
-  ".": "7.21.0"
+  ".": "7.21.1"
 }
diff --git a/.stats.yml b/.stats.yml
index e2794c72..48e48092 100644
--- a/.stats.yml
+++ b/.stats.yml
@@ -1,4 +1,4 @@
 configured_endpoints: 134
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/courier/courier-b053468fefe6d757f86f3233ebbc52d80329ed2a6e7a6740fee01e4028a4c3b9.yml
-openapi_spec_hash: 416835e693de0fe19945be90a787d3f3
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/courier/courier-5c878919b3df530781ebcd4ab1cda83606304da75c53fe0817d4c725d5bbbe73.yml
+openapi_spec_hash: dd37022222543ff064200e65e4b82f59
 config_hash: 8d28dbeabe9d4dcc7d5b8c021a4cbbd7
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a38f1cab..08b03e0c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,14 @@
 # Changelog
 
+## 7.21.1 (2026-07-25)
+
+Full Changelog: [v7.21.0...v7.21.1](https://github.com/trycourier/courier-node/compare/v7.21.0...v7.21.1)
+
+### Documentation
+
+* **openapi:** describe user topic-preference fields explicitly ([#172](https://github.com/trycourier/courier-node/issues/172)) ([dba1cfc](https://github.com/trycourier/courier-node/commit/dba1cfc46d8dd557223158758a77ca3fd5a8a03d))
+* **openapi:** rewrite operation descriptions for agents and SEO ([#174](https://github.com/trycourier/courier-node/issues/174)) ([db95d94](https://github.com/trycourier/courier-node/commit/db95d94acdcfbf50bceb7282fc5cd393d539f7f9))
+
 ## 7.21.0 (2026-07-23)
 
 Full Changelog: [v7.20.0...v7.21.0](https://github.com/trycourier/courier-node/compare/v7.20.0...v7.21.0)
diff --git a/package.json b/package.json
index 607827f8..748d340e 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@trycourier/courier",
-  "version": "7.21.0",
+  "version": "7.21.1",
   "description": "The official TypeScript library for the Courier API",
   "author": "Courier <support@courier.com>",
   "types": "dist/index.d.ts",
diff --git a/src/resources/audiences.ts b/src/resources/audiences.ts
index 2e2d99d1..d92378a7 100644
--- a/src/resources/audiences.ts
+++ b/src/resources/audiences.ts
@@ -9,14 +9,16 @@ import { path } from '../internal/utils/path';
 
 export class Audiences extends APIResource {
   /**
-   * Returns the specified audience by id.
+   * Returns one audience with its name, description, and the filter and AND or OR
+   * operator that decide which users belong to it.
    */
   retrieve(audienceID: string, options?: RequestOptions): APIPromise<Audience> {
     return this._client.get(path`/audiences/${audienceID}`, options);
   }
 
   /**
-   * Creates or updates audience.
+   * Creates or replaces an audience from a filter and an AND or OR operator.
+   * Membership recalculates automatically as profiles change.
    */
   update(
     audienceID: string,
@@ -27,7 +29,8 @@ export class Audiences extends APIResource {
   }
 
   /**
-   * Get the audiences associated with the authorization token.
+   * Returns the audiences in the workspace with paging. Audiences are filter-based
+   * groups that recalculate as user profiles change.
    */
   list(
     query: AudienceListParams | null | undefined = {},
@@ -37,7 +40,8 @@ export class Audiences extends APIResource {
   }
 
   /**
-   * Deletes the specified audience.
+   * Deletes an audience permanently, so update any caller sending to it by audience
+   * id first. Those sends fail once the audience is gone.
    */
   delete(audienceID: string, options?: RequestOptions): APIPromise<void> {
     return this._client.delete(path`/audiences/${audienceID}`, {
@@ -47,7 +51,8 @@ export class Audiences extends APIResource {
   }
 
   /**
-   * Get list of members of an audience.
+   * Returns the users currently matching an audience filter, with paging. Membership
+   * is recalculated, so results shift as profiles change.
    */
   listMembers(
     audienceID: string,
diff --git a/src/resources/audit-events.ts b/src/resources/audit-events.ts
index 11c35fc4..388bf705 100644
--- a/src/resources/audit-events.ts
+++ b/src/resources/audit-events.ts
@@ -8,14 +8,16 @@ import { path } from '../internal/utils/path';
 
 export class AuditEvents extends APIResource {
   /**
-   * Fetch a specific audit event by ID.
+   * Returns one audit event by id, including the actor who performed it, the target
+   * they changed, the source, the event type, and a timestamp.
    */
   retrieve(auditEventID: string, options?: RequestOptions): APIPromise<AuditEvent> {
     return this._client.get(path`/audit-events/${auditEventID}`, options);
   }
 
   /**
-   * Fetch the list of audit events
+   * Returns the workspace's audit event log with cursor paging. Each event records
+   * the actor, target, source, type, and timestamp of a change.
    */
   list(
     query: AuditEventListParams | null | undefined = {},
diff --git a/src/resources/auth.ts b/src/resources/auth.ts
index 0ce3ab19..6392e2f0 100644
--- a/src/resources/auth.ts
+++ b/src/resources/auth.ts
@@ -6,7 +6,8 @@ import { RequestOptions } from '../internal/request-options';
 
 export class Auth extends APIResource {
   /**
-   * Returns a new access token.
+   * Returns a JWT for authenticating client-side SDKs such as the Inbox. You supply
+   * the scope and an expires_in duration, both required.
    *
    * @example
    * ```ts
diff --git a/src/resources/automations/automations.ts b/src/resources/automations/automations.ts
index 6448ce72..51a38487 100644
--- a/src/resources/automations/automations.ts
+++ b/src/resources/automations/automations.ts
@@ -10,7 +10,8 @@ export class Automations extends APIResource {
   invoke: InvokeAPI.Invoke = new InvokeAPI.Invoke(this._client);
 
   /**
-   * Get the list of automations.
+   * Lists the workspace's saved automation templates, each with its id and a cursor
+   * for paging to the next page of results.
    *
    * @example
    * ```ts
diff --git a/src/resources/automations/invoke.ts b/src/resources/automations/invoke.ts
index dbfebedf..487cff6c 100644
--- a/src/resources/automations/invoke.ts
+++ b/src/resources/automations/invoke.ts
@@ -8,10 +8,8 @@ import { path } from '../../internal/utils/path';
 
 export class Invoke extends APIResource {
   /**
-   * Invoke an ad hoc automation run. This endpoint accepts a JSON payload with a
-   * series of automation steps. For information about what steps are available,
-   * checkout the ad hoc automation guide
-   * [here](https://www.courier.com/docs/automations/steps/).
+   * Runs a series of automation steps supplied inline, without a saved template, and
+   * returns a runId.
    *
    * @example
    * ```ts
@@ -41,7 +39,8 @@ export class Invoke extends APIResource {
   }
 
   /**
-   * Invoke an automation run from an automation template.
+   * Starts an automation run from a saved template for one recipient, with optional
+   * data and profile, and returns a runId.
    *
    * @example
    * ```ts
diff --git a/src/resources/brands.ts b/src/resources/brands.ts
index c66441a1..bb06c9e4 100644
--- a/src/resources/brands.ts
+++ b/src/resources/brands.ts
@@ -10,8 +10,8 @@ import { path } from '../internal/utils/path';
 
 export class Brands extends APIResource {
   /**
-   * Create a new brand. Requires `name` and `settings` (with at least
-   * `colors.primary` and `colors.secondary`).
+   * Creates a brand from a name and settings, including primary and secondary
+   * colors. Brands supply the logo, colors, and styling that templates render with.
    *
    * @example
    * ```ts
@@ -28,7 +28,8 @@ export class Brands extends APIResource {
   }
 
   /**
-   * Fetch a specific brand by brand ID.
+   * Returns one brand by id, including its colors, logo and styling settings,
+   * Handlebars snippets, and published version.
    *
    * @example
    * ```ts
@@ -40,7 +41,8 @@ export class Brands extends APIResource {
   }
 
   /**
-   * Replace an existing brand with the supplied values.
+   * Replaces a brand with the values you supply, so send the complete settings and
+   * snippets rather than only the fields you want changed.
    *
    * @example
    * ```ts
@@ -54,7 +56,8 @@ export class Brands extends APIResource {
   }
 
   /**
-   * Get the list of brands.
+   * Lists the workspace's brands. Every entry carries its name, styling settings,
+   * snippets, and published version.
    *
    * @example
    * ```ts
@@ -69,7 +72,8 @@ export class Brands extends APIResource {
   }
 
   /**
-   * Delete a brand by brand ID.
+   * Deletes a brand by id. Reassign any template or tenant that references it before
+   * deleting to keep their styling intact.
    *
    * @example
    * ```ts
diff --git a/src/resources/digests/schedules.ts b/src/resources/digests/schedules.ts
index 671bd1d6..1241183c 100644
--- a/src/resources/digests/schedules.ts
+++ b/src/resources/digests/schedules.ts
@@ -9,9 +9,8 @@ import { path } from '../../internal/utils/path';
 
 export class Schedules extends APIResource {
   /**
-   * List the digest instances for a schedule. Each instance represents the events
-   * accumulated for a single user against the schedule, and can be used to monitor
-   * digest accumulation before the digest is released.
+   * Returns the digest instances for a schedule, one per user, with cursor paging.
+   * Use it to see what has accumulated before a digest releases.
    */
   listInstances(
     scheduleID: string,
diff --git a/src/resources/inbound.ts b/src/resources/inbound.ts
index 56d5d272..b1318f85 100644
--- a/src/resources/inbound.ts
+++ b/src/resources/inbound.ts
@@ -6,7 +6,8 @@ import { RequestOptions } from '../internal/request-options';
 
 export class Inbound extends APIResource {
   /**
-   * Courier Track Event
+   * Records an inbound event that can trigger a journey. Requires an event name, a
+   * messageId you generate, a type, and a properties object.
    *
    * @example
    * ```ts
diff --git a/src/resources/journeys/journeys.ts b/src/resources/journeys/journeys.ts
index 5704de16..82373c34 100644
--- a/src/resources/journeys/journeys.ts
+++ b/src/resources/journeys/journeys.ts
@@ -26,12 +26,8 @@ export class Journeys extends APIResource {
   templates: TemplatesAPI.Templates = new TemplatesAPI.Templates(this._client);
 
   /**
-   * Create a journey. Defaults to `DRAFT` state; pass `state: "PUBLISHED"` to
-   * publish on create. Send nodes are not allowed on `POST`. The standard flow is:
-   * create the journey shell here, add notification templates with
-   * `POST /journeys/{templateId}/templates`, then wire them into the journey with
-   * `PUT /journeys/{templateId}`. Call `POST /journeys/{templateId}/publish` to
-   * publish a draft after the fact.
+   * Creates a journey from a set of nodes, in draft state unless you pass a
+   * published state. Send nodes cannot be included until their templates exist.
    *
    * @example
    * ```ts
@@ -72,7 +68,8 @@ export class Journeys extends APIResource {
   }
 
   /**
-   * Get the list of journeys.
+   * Lists the workspace's journeys, each carrying a name, state, and enabled flag.
+   * Paged by cursor.
    *
    * @example
    * ```ts
@@ -87,8 +84,8 @@ export class Journeys extends APIResource {
   }
 
   /**
-   * Archive a journey. Archived journeys cannot be invoked. Existing journey runs
-   * continue to completion.
+   * Archives a journey so it can no longer be invoked. Runs already in flight
+   * continue to completion, so archiving never strands a user mid-sequence.
    *
    * @example
    * ```ts
@@ -103,12 +100,8 @@ export class Journeys extends APIResource {
   }
 
   /**
-   * Cancel journey runs. The request body must include EXACTLY ONE of
-   * `cancelation_token` (cancels every run associated with the token) or `run_id`
-   * (cancels a single tenant-scoped run). Supplying both or neither returns a `400`.
-   * A `run_id` that does not match a run for the tenant returns `404`. Cancelation
-   * is idempotent: a run that has already finished (`PROCESSED`/`ERROR`) or was
-   * already `CANCELED` is left unchanged and its current status is returned.
+   * Cancels in-flight journey runs, either every run sharing a cancelation token or
+   * one run by id. Use it to stop a sequence when the event resolves.
    *
    * @example
    * ```ts
@@ -122,8 +115,8 @@ export class Journeys extends APIResource {
   }
 
   /**
-   * Invoke a journey by id or alias to start a new run. The response includes a
-   * `runId` identifying the run.
+   * Starts a journey run for one user and returns a runId. Runs execute
+   * asynchronously, so the response arrives before any message is sent.
    *
    * @example
    * ```ts
@@ -145,7 +138,8 @@ export class Journeys extends APIResource {
   }
 
   /**
-   * List published versions of a journey, ordered most recent first.
+   * Lists a journey's published versions, most recent first, so you have a version
+   * id to roll back to. Paged by cursor.
    *
    * @example
    * ```ts
@@ -158,9 +152,8 @@ export class Journeys extends APIResource {
   }
 
   /**
-   * Publish the current draft as a new version. Body is optional; pass
-   * `{ "version": "vN" }` to roll back to a prior version instead. Returns 404 if
-   * the journey has no draft to publish.
+   * Publishes a journey's current draft as a new version, making it live for new
+   * runs. Pass a version instead to roll back to an earlier one.
    *
    * @example
    * ```ts
@@ -176,11 +169,8 @@ export class Journeys extends APIResource {
   }
 
   /**
-   * Replace the journey draft. Updates the working draft only; call
-   * `POST /journeys/{templateId}/publish` to make it live, or pass
-   * `state: "PUBLISHED"` in this request to publish immediately. Send-node
-   * `template` ids must already exist and be scoped to this journey, and node ids
-   * must not be claimed by another journey.
+   * Replaces a journey's working draft, leaving the published version live until you
+   * publish. Reach for this when editing a journey already running.
    *
    * @example
    * ```ts
diff --git a/src/resources/journeys/templates.ts b/src/resources/journeys/templates.ts
index 8c0b4891..6af914e8 100644
--- a/src/resources/journeys/templates.ts
+++ b/src/resources/journeys/templates.ts
@@ -41,9 +41,8 @@ export class Templates extends APIResource {
   }
 
   /**
-   * Fetch a journey-scoped notification template by id. Pass `?version=draft`
-   * (default `published`) to retrieve the working draft, or `?version=vN` for a
-   * historical version.
+   * Returns a journey's own notification template with its name, brand, subscription
+   * topic, and content. Defaults to the published version.
    *
    * @example
    * ```ts
@@ -81,8 +80,8 @@ export class Templates extends APIResource {
   }
 
   /**
-   * Archive the journey-scoped notification template. Archived templates cannot be
-   * sent.
+   * Archives one journey's notification template, preventing further sends. Detach
+   * any send node referencing it beforehand.
    *
    * @example
    * ```ts
@@ -100,8 +99,8 @@ export class Templates extends APIResource {
   }
 
   /**
-   * List published versions of the journey-scoped notification template, ordered
-   * most recent first.
+   * Lists the published versions of a template that belongs to a journey, most
+   * recent first. Paged by cursor.
    *
    * @example
    * ```ts
@@ -121,9 +120,8 @@ export class Templates extends APIResource {
   }
 
   /**
-   * Publish the current draft of the journey-scoped notification template as a new
-   * version. Optionally roll back to a prior version by passing
-   * `{ "version": "vN" }`.
+   * Publishes a journey-scoped template's draft as a new version. Pass a version
+   * instead to roll back the template to an earlier publish.
    *
    * @example
    * ```ts
@@ -201,7 +199,8 @@ export class Templates extends APIResource {
   }
 
   /**
-   * Replace the journey-scoped notification template draft.
+   * Replaces the draft content of one journey's notification template. Publish it
+   * before send nodes referencing it render the change.
    *
    * @example
    * ```ts
@@ -228,11 +227,8 @@ export class Templates extends APIResource {
   }
 
   /**
-   * Retrieve the elemental content of a journey-scoped notification template. The
-   * response contains the versioned elements along with their content checksums,
-   * which can be used to detect changes between versions. Pass `?version=draft`
-   * (default `published`) to retrieve the working draft, or `?version=vN` for a
-   * historical version.
+   * Returns the Elemental elements and version of a journey-scoped template's
+   * content. Compare versions to see what changed between publishes.
    *
    * @example
    * ```ts
diff --git a/src/resources/lists/lists.ts b/src/resources/lists/lists.ts
index 3967f269..55f40a5c 100644
--- a/src/resources/lists/lists.ts
+++ b/src/resources/lists/lists.ts
@@ -21,14 +21,16 @@ export class Lists extends APIResource {
   subscriptions: SubscriptionsAPI.Subscriptions = new SubscriptionsAPI.Subscriptions(this._client);
 
   /**
-   * Returns a list based on the list ID provided.
+   * Returns one list by id with its name and created and updated timestamps. Fetch
+   * its subscribers separately with the subscriptions endpoint.
    */
   retrieve(listID: string, options?: RequestOptions): APIPromise<SubscriptionList> {
     return this._client.get(path`/lists/${listID}`, options);
   }
 
   /**
-   * Create or replace an existing list with the supplied values.
+   * Creates or replaces a list from a name and preferences. Subscribers are managed
+   * through the separate subscriptions endpoints.
    */
   update(listID: string, body: ListUpdateParams, options?: RequestOptions): APIPromise<void> {
     return this._client.put(path`/lists/${listID}`, {
@@ -39,7 +41,8 @@ export class Lists extends APIResource {
   }
 
   /**
-   * Returns all of the lists, with the ability to filter based on a pattern.
+   * Returns the workspace's lists, filterable by a pattern to fetch a subset such as
+   * every regional list. Paged by cursor.
    */
   list(
     query: ListListParams | null | undefined = {},
@@ -49,7 +52,8 @@ export class Lists extends APIResource {
   }
 
   /**
-   * Delete a list by list ID.
+   * Deletes a list, halting sends that target it. A previously deleted list can be
+   * brought back with the companion restore endpoint.
    */
   delete(listID: string, options?: RequestOptions): APIPromise<void> {
     return this._client.delete(path`/lists/${listID}`, {
@@ -59,7 +63,8 @@ export class Lists extends APIResource {
   }
 
   /**
-   * Restore a previously deleted list.
+   * Restores a previously deleted list along with its subscribers, so a list removed
+   * by mistake can be brought back rather than rebuilt.
    */
   restore(listID: string, body: ListRestoreParams, options?: RequestOptions): APIPromise<void> {
     return this._client.put(path`/lists/${listID}/restore`, {
diff --git a/src/resources/lists/subscriptions.ts b/src/resources/lists/subscriptions.ts
index 4878baec..69937802 100644
--- a/src/resources/lists/subscriptions.ts
+++ b/src/resources/lists/subscriptions.ts
@@ -10,7 +10,8 @@ import { path } from '../../internal/utils/path';
 
 export class Subscriptions extends APIResource {
   /**
-   * Get the list's subscriptions.
+   * Returns the users subscribed to a list with paging, each with the preferences
+   * recorded for that subscription.
    */
   list(
     listID: string,
@@ -45,8 +46,8 @@ export class Subscriptions extends APIResource {
   }
 
   /**
-   * Subscribe a user to an existing list (note: if the List does not exist, it will
-   * be automatically created).
+   * Subscribes one user to a list, creating the list if it does not yet exist.
+   * Optional preferences apply to this subscription only.
    */
   subscribeUser(
     userID: string,
@@ -62,7 +63,8 @@ export class Subscriptions extends APIResource {
   }
 
   /**
-   * Delete a subscription to a list by list ID and user ID.
+   * Removes one user's subscription to a list, addressed by list id and user id. The
+   * user's profile and other subscriptions are separate resources.
    */
   unsubscribeUser(
     userID: string,
diff --git a/src/resources/messages.ts b/src/resources/messages.ts
index 4db8b9dc..2acdf413 100644
--- a/src/resources/messages.ts
+++ b/src/resources/messages.ts
@@ -8,14 +8,16 @@ import { path } from '../internal/utils/path';
 
 export class Messages extends APIResource {
   /**
-   * Fetch the status of a message you've previously sent.
+   * Returns a sent message's status, recipient, event, and per-provider delivery
+   * detail, with timestamps for enqueued, sent, delivered, opened, and clicked.
    */
   retrieve(messageID: string, options?: RequestOptions): APIPromise<MessageRetrieveResponse> {
     return this._client.get(path`/messages/${messageID}`, options);
   }
 
   /**
-   * Fetch the statuses of messages you've previously sent.
+   * Returns previously sent messages, most recent first, each carrying its status,
+   * recipient, channel, and provider. Paged by cursor.
    */
   list(
     query: MessageListParams | null | undefined = {},
@@ -25,25 +27,24 @@ export class Messages extends APIResource {
   }
 
   /**
-   * Cancel a message that is currently in the process of being delivered. A
-   * well-formatted API call to the cancel message API will return either `200`
-   * status code for a successful cancellation or `409` status code for an
-   * unsuccessful cancellation. Both cases will include the actual message record in
-   * the response body (see details below).
+   * Cancels a message that is still in the delivery pipeline and returns the message
+   * record with its resulting canceled or failed status.
    */
   cancel(messageID: string, options?: RequestOptions): APIPromise<MessageDetails> {
     return this._client.post(path`/messages/${messageID}/cancel`, options);
   }
 
   /**
-   * Get message content
+   * Returns the rendered content Courier delivered for a message, broken out per
+   * channel, to confirm what the recipient received.
    */
   content(messageID: string, options?: RequestOptions): APIPromise<MessageContentResponse> {
     return this._client.get(path`/messages/${messageID}/output`, options);
   }
 
   /**
-   * Fetch the array of events of a message you've previously sent.
+   * Returns the ordered event history for a sent message, one entry per status
+   * transition with its timestamp.
    */
   history(
     messageID: string,
@@ -54,11 +55,8 @@ export class Messages extends APIResource {
   }
 
   /**
-   * Resend a previously sent message. The original send request is loaded from
-   * storage and a brand-new send is enqueued for the same recipient and content,
-   * producing a **new** `messageId` — the original message is not modified.
-   * Throttled by a per-message rate limit; a repeat inside the limit window returns
-   * `429 Too Many Requests`.
+   * Resends a previously sent message to the same recipient and content, returning a
+   * new messageId. The original send request is not modified.
    */
   resend(messageID: string, options?: RequestOptions): APIPromise<MessageResendResponse> {
     return this._client.post(path`/messages/${messageID}/resend`, options);
diff --git a/src/resources/notifications/checks.ts b/src/resources/notifications/checks.ts
index 490d8389..29d683cd 100644
--- a/src/resources/notifications/checks.ts
+++ b/src/resources/notifications/checks.ts
@@ -9,7 +9,8 @@ import { path } from '../../internal/utils/path';
 
 export class Checks extends APIResource {
   /**
-   * Replace the submission checks for a notification template.
+   * Replaces the approval checks on a template submission with the complete set
+   * supplied in the request body.
    *
    * @example
    * ```ts
@@ -38,7 +39,8 @@ export class Checks extends APIResource {
   }
 
   /**
-   * Retrieve the submission checks for a notification template.
+   * Returns the approval checks recorded for a template submission, each with its
+   * pass or fail result.
    *
    * @example
    * ```ts
@@ -58,7 +60,8 @@ export class Checks extends APIResource {
   }
 
   /**
-   * Cancel a submission for a notification template.
+   * Cancels a pending template submission, withdrawing it from the approval
+   * workflow. The template stays in draft and can be resubmitted later.
    *
    * @example
    * ```ts
diff --git a/src/resources/notifications/notifications.ts b/src/resources/notifications/notifications.ts
index 651726e2..5d9efb26 100644
--- a/src/resources/notifications/notifications.ts
+++ b/src/resources/notifications/notifications.ts
@@ -69,7 +69,8 @@ export class Notifications extends APIResource {
   }
 
   /**
-   * List notification templates in your workspace.
+   * Lists the workspace's notification templates. Each carries a name, tags, brand,
+   * routing, and its draft or published state.
    *
    * @example
    * ```ts
@@ -84,7 +85,8 @@ export class Notifications extends APIResource {
   }
 
   /**
-   * Archive a notification template.
+   * Archives a notification template, preventing new sends from referencing it. The
+   * template stays retrievable for its version history.
    *
    * @example
    * ```ts
@@ -99,12 +101,9 @@ export class Notifications extends APIResource {
   }
 
   /**
-   * Duplicate a notification template. Creates a standalone copy within the same
-   * workspace and environment, with " COPY" appended to the title. The copy clones
-   * the source draft's tags, brand, subscription topic, routing strategy, channels,
-   * and content, and is always created as a standalone template (it is not linked to
-   * any journey or broadcast, even if the source was). Templates that are scoped to
-   * a journey or a broadcast cannot be duplicated through this endpoint.
+   * Copies a notification template within the same workspace and environment,
+   * appending " COPY" to the title. The copy is standalone and independently
+   * editable.
    *
    * @example
    * ```ts
@@ -117,7 +116,8 @@ export class Notifications extends APIResource {
   }
 
   /**
-   * List versions of a notification template.
+   * Returns a notification template's published versions, most recent first, for
+   * comparison or rollback. Paged.
    *
    * @example
    * ```ts
@@ -155,9 +155,8 @@ export class Notifications extends APIResource {
   }
 
   /**
-   * Replace the elemental content of a notification template. Overwrites all
-   * elements in the template with the provided content. Only supported for V2
-   * (elemental) templates.
+   * Replaces all Elemental content in a template, overwriting every existing
+   * element. Supported for V2 templates only, not V1 blocks and channels.
    *
    * @example
    * ```ts
@@ -180,8 +179,8 @@ export class Notifications extends APIResource {
   }
 
   /**
-   * Update a single element within a notification template. Only supported for V2
-   * (elemental) templates.
+   * Replaces one Elemental element in a template, addressed by its element id.
+   * Supported for V2 templates only, not V1 blocks and channels.
    *
    * @example
    * ```ts
@@ -204,9 +203,8 @@ export class Notifications extends APIResource {
   }
 
   /**
-   * Set locale-specific content overrides for a notification template. Each element
-   * override must reference an existing element by ID. Only supported for V2
-   * (elemental) templates.
+   * Sets locale-specific content overrides for a template. Each override must
+   * reference an element that already exists in the default content.
    *
    * @example
    * ```ts
@@ -231,7 +229,8 @@ export class Notifications extends APIResource {
   }
 
   /**
-   * Replace a notification template. All fields are required.
+   * Replaces a notification template in full, so send every field rather than only
+   * the ones you want changed. Publish separately to make it live.
    *
    * @example
    * ```ts
@@ -261,10 +260,8 @@ export class Notifications extends APIResource {
   }
 
   /**
-   * Retrieve the content of a notification template. The response shape depends on
-   * whether the template uses V1 (blocks/channels) or V2 (elemental) content. Use
-   * the `version` query parameter to select draft, published, or a specific
-   * historical version.
+   * Returns a template's content and checksum. V2 templates return Elemental
+   * elements, while V1 templates return blocks and channels instead.
    *
    * @example
    * ```ts
diff --git a/src/resources/profiles/lists.ts b/src/resources/profiles/lists.ts
index bc21195f..7824e70f 100644
--- a/src/resources/profiles/lists.ts
+++ b/src/resources/profiles/lists.ts
@@ -9,7 +9,8 @@ import { path } from '../../internal/utils/path';
 
 export class Lists extends APIResource {
   /**
-   * Returns the subscribed lists for a specified user.
+   * Returns the lists a user is subscribed to, with paging. Use it to check what a
+   * recipient will receive before sending to a list.
    */
   retrieve(
     userID: string,
@@ -20,15 +21,16 @@ export class Lists extends APIResource {
   }
 
   /**
-   * Removes all list subscriptions for given user.
+   * Removes every list subscription for a user at once. Their profile and
+   * preferences are untouched, so this only affects list-targeted sends.
    */
   delete(userID: string, options?: RequestOptions): APIPromise<ListDeleteResponse> {
     return this._client.delete(path`/profiles/${userID}/lists`, options);
   }
 
   /**
-   * Subscribes the given user to one or more lists. If the list does not exist, it
-   * will be created.
+   * Subscribes a user to one or more lists, creating any list that does not yet
+   * exist. Optional preferences apply to each subscription.
    */
   subscribe(
     userID: string,
diff --git a/src/resources/profiles/profiles.ts b/src/resources/profiles/profiles.ts
index 358fae68..7a8c6c4c 100644
--- a/src/resources/profiles/profiles.ts
+++ b/src/resources/profiles/profiles.ts
@@ -20,8 +20,8 @@ export class Profiles extends APIResource {
   lists: ListsAPI.Lists = new ListsAPI.Lists(this._client);
 
   /**
-   * Merge the supplied values with an existing profile or create a new profile if
-   * one doesn't already exist.
+   * Merges the supplied values into a user's profile, creating it if absent and
+   * leaving any key you omit untouched. Prefer this for everyday writes.
    */
   create(
     userID: string,
@@ -32,14 +32,16 @@ export class Profiles extends APIResource {
   }
 
   /**
-   * Returns the specified user profile.
+   * Returns a user's stored profile and preferences, including the email address,
+   * phone number, and push tokens Courier can reach them on.
    */
   retrieve(userID: string, options?: RequestOptions): APIPromise<ProfileRetrieveResponse> {
     return this._client.get(path`/profiles/${userID}`, options);
   }
 
   /**
-   * Update a profile
+   * Applies a JSON Patch to a user profile, adding, removing, or replacing
+   * individual fields without sending the whole object.
    */
   update(userID: string, body: ProfileUpdateParams, options?: RequestOptions): APIPromise<void> {
     return this._client.patch(path`/profiles/${userID}`, {
@@ -50,7 +52,8 @@ export class Profiles extends APIResource {
   }
 
   /**
-   * Deletes the specified user profile.
+   * Deletes a user's profile and stored contact details. List subscriptions and
+   * preferences are separate resources, so remove those too if required.
    */
   delete(userID: string, options?: RequestOptions): APIPromise<void> {
     return this._client.delete(path`/profiles/${userID}`, {
@@ -60,11 +63,8 @@ export class Profiles extends APIResource {
   }
 
   /**
-   * When using `PUT`, be sure to include all the key-value pairs required by the
-   * recipient's profile. Any key-value pairs that exist in the profile but fail to
-   * be included in the `PUT` request will be removed from the profile. Remember, a
-   * `PUT` update is a full replacement of the data. For partial updates, use the
-   * [Patch](https://www.courier.com/docs/reference/profiles/patch/) request.
+   * Overwrites a user profile in full, removing any key absent from the request
+   * body. Use the patch endpoint when changing a single field.
    */
   replace(
     userID: string,
diff --git a/src/resources/providers/catalog.ts b/src/resources/providers/catalog.ts
index b49b5b0a..956f21dc 100644
--- a/src/resources/providers/catalog.ts
+++ b/src/resources/providers/catalog.ts
@@ -8,10 +8,8 @@ import { RequestOptions } from '../../internal/request-options';
 
 export class Catalog extends APIResource {
   /**
-   * Returns the catalog of available provider types with their display names,
-   * descriptions, and configuration schema fields (snake_case, with `type` and
-   * `required`). Providers with no configurable schema return only `provider`,
-   * `name`, and `description`.
+   * Returns the provider types Courier supports, each with a display name,
+   * description, and the configuration fields it requires.
    */
   list(
     query: CatalogListParams | null | undefined = {},
diff --git a/src/resources/providers/providers.ts b/src/resources/providers/providers.ts
index 4c649aa2..6719aed7 100644
--- a/src/resources/providers/providers.ts
+++ b/src/resources/providers/providers.ts
@@ -13,34 +13,32 @@ export class Providers extends APIResource {
   catalog: CatalogAPI.Catalog = new CatalogAPI.Catalog(this._client);
 
   /**
-   * Create a new provider configuration. The `provider` field must be a known
-   * Courier provider key (see catalog).
+   * Configures a provider integration from a Courier provider key and its settings.
+   * Check the catalog endpoint for the schema each provider expects.
    */
   create(body: ProviderCreateParams, options?: RequestOptions): APIPromise<Provider> {
     return this._client.post('/providers', { body, ...options });
   }
 
   /**
-   * Fetch a single provider configuration by ID.
+   * Returns one configured provider by id, including its channel, provider key,
+   * alias, title, and current settings.
    */
   retrieve(id: string, options?: RequestOptions): APIPromise<Provider> {
     return this._client.get(path`/providers/${id}`, options);
   }
 
   /**
-   * Replace an existing provider configuration. The `provider` key is required and
-   * determines which provider-specific settings schema is applied. All other fields
-   * are optional — omitted fields are cleared from the stored configuration (this is
-   * a full replacement, not a partial merge). Changing the provider type for an
-   * existing configuration is not supported.
+   * Replaces a provider's configuration in full, clearing any field you omit rather
+   * than merging it. Send the complete settings object.
    */
   update(id: string, body: ProviderUpdateParams, options?: RequestOptions): APIPromise<Provider> {
     return this._client.put(path`/providers/${id}`, { body, ...options });
   }
 
   /**
-   * List configured provider integrations for the current workspace. Supports
-   * cursor-based pagination.
+   * Lists the provider integrations configured in the workspace, one entry per
+   * channel and provider key with its alias and settings.
    */
   list(
     query: ProviderListParams | null | undefined = {},
@@ -50,8 +48,8 @@ export class Providers extends APIResource {
   }
 
   /**
-   * Delete a provider configuration. Returns 409 if the provider is still referenced
-   * by routing or notifications.
+   * Deletes a provider configuration, which fails while routing strategies or
+   * templates still reference it. Update those references first.
    */
   delete(id: string, options?: RequestOptions): APIPromise<void> {
     return this._client.delete(path`/providers/${id}`, {
diff --git a/src/resources/requests.ts b/src/resources/requests.ts
index 7c287eea..cdb84143 100644
--- a/src/resources/requests.ts
+++ b/src/resources/requests.ts
@@ -8,7 +8,8 @@ import { path } from '../internal/utils/path';
 
 export class Requests extends APIResource {
   /**
-   * Archive message
+   * Archives a send request by its request id. Use it to remove test sends or
+   * superseded requests from the message list without deleting them.
    */
   archive(requestID: string, options?: RequestOptions): APIPromise<void> {
     return this._client.put(path`/requests/${requestID}/archive`, {
diff --git a/src/resources/routing-strategies.ts b/src/resources/routing-strategies.ts
index 35593c32..ae9ce8d5 100644
--- a/src/resources/routing-strategies.ts
+++ b/src/resources/routing-strategies.ts
@@ -35,8 +35,8 @@ export class RoutingStrategies extends APIResource {
   }
 
   /**
-   * Retrieve a routing strategy by ID. Returns the full entity including routing
-   * content and metadata.
+   * Returns one routing strategy by id with its name, tags, channels, and the
+   * routing rules that decide provider order and fallback.
    *
    * @example
    * ```ts
@@ -83,8 +83,8 @@ export class RoutingStrategies extends APIResource {
   }
 
   /**
-   * List notification templates associated with a routing strategy. Includes
-   * template metadata only, not full content.
+   * Returns the notification templates using a routing strategy, with paging. Check
+   * this before changing a strategy that templates depend on.
    *
    * @example
    * ```ts
diff --git a/src/resources/send.ts b/src/resources/send.ts
index bc35c9f5..fe629e78 100644
--- a/src/resources/send.ts
+++ b/src/resources/send.ts
@@ -7,7 +7,8 @@ import { RequestOptions } from '../internal/request-options';
 
 export class Send extends APIResource {
   /**
-   * Send a message to one or more recipients.
+   * Sends a message to one or more recipients and returns a requestId. Courier
+   * routes it to email, SMS, push, chat, or in-app based on your rules.
    *
    * @example
    * ```ts
diff --git a/src/resources/tenants/preferences/items.ts b/src/resources/tenants/preferences/items.ts
index 5b93e99e..f06e64c5 100644
--- a/src/resources/tenants/preferences/items.ts
+++ b/src/resources/tenants/preferences/items.ts
@@ -9,7 +9,8 @@ import { path } from '../../../internal/utils/path';
 
 export class Items extends APIResource {
   /**
-   * Create or Replace Default Preferences For Topic
+   * Sets a tenant's default opt-in status for one subscription topic, which applies
+   * to every member unless a user sets their own override.
    *
    * @example
    * ```ts
@@ -31,7 +32,8 @@ export class Items extends APIResource {
   }
 
   /**
-   * Remove Default Preferences For Topic
+   * Removes a tenant's default preference for one subscription topic, addressed by
+   * tenant id and topic id.
    *
    * @example
    * ```ts
diff --git a/src/resources/tenants/templates/templates.ts b/src/resources/tenants/templates/templates.ts
index 262ca3d5..7bd80dcf 100644
--- a/src/resources/tenants/templates/templates.ts
+++ b/src/resources/tenants/templates/templates.ts
@@ -14,7 +14,8 @@ export class Templates extends APIResource {
   versions: VersionsAPI.Versions = new VersionsAPI.Versions(this._client);
 
   /**
-   * Get a Template in Tenant
+   * Returns a tenant's notification template with its content, version, and created,
+   * updated, and published timestamps.
    *
    * @example
    * ```ts
@@ -34,7 +35,8 @@ export class Templates extends APIResource {
   }
 
   /**
-   * List Templates in Tenant
+   * Lists a tenant's notification templates, each carrying its version and published
+   * timestamp. Paged.
    *
    * @example
    * ```ts
@@ -52,12 +54,8 @@ export class Templates extends APIResource {
   }
 
   /**
-   * Deletes the tenant's notification template with the given `template_id`.
-   *
-   * Returns **204 No Content** with an empty body on success.
-   *
-   * Returns **404** if there is no template with this ID for the tenant, including a
-   * second `DELETE` after a successful removal.
+   * Deletes a tenant's notification template by id. Sends for that tenant then use
+   * the workspace template registered under the same id.
    *
    * @example
    * ```ts
@@ -75,10 +73,8 @@ export class Templates extends APIResource {
   }
 
   /**
-   * Publishes a specific version of a notification template for a tenant.
-   *
-   * The template must already exist in the tenant's notification map. If no version
-   * is specified, defaults to publishing the "latest" version.
+   * Publishes a version of a tenant's notification template, making it the content
+   * that tenant's sends render from until you publish another.
    *
    * @example
    * ```ts
@@ -101,13 +97,8 @@ export class Templates extends APIResource {
   }
 
   /**
-   * Creates or updates a notification template for a tenant.
-   *
-   * If the template already exists for the tenant, it will be updated (200).
-   * Otherwise, a new template is created (201).
-   *
-   * Optionally publishes the template immediately if the `published` flag is set to
-   * true.
+   * Creates or updates a notification template scoped to one tenant, letting a
+   * tenant override the content the workspace template would send.
    *
    * @example
    * ```ts
diff --git a/src/resources/tenants/templates/versions.ts b/src/resources/tenants/templates/versions.ts
index 62a07d6d..326383f1 100644
--- a/src/resources/tenants/templates/versions.ts
+++ b/src/resources/tenants/templates/versions.ts
@@ -8,13 +8,8 @@ import { path } from '../../../internal/utils/path';
 
 export class Versions extends APIResource {
   /**
-   * Fetches a specific version of a tenant template.
-   *
-   * Supports the following version formats:
-   *
-   * - `latest` - The most recent version of the template
-   * - `published` - The currently published version
-   * - `v{version}` - A specific version (e.g., "v1", "v2", "v1.0.0")
+   * Returns one version of a tenant template, addressed by version number or by
+   * latest, with its content and publish timestamp.
    *
    * @example
    * ```ts
diff --git a/src/resources/tenants/tenants.ts b/src/resources/tenants/tenants.ts
index 1ac5e1f0..70a36845 100644
--- a/src/resources/tenants/tenants.ts
+++ b/src/resources/tenants/tenants.ts
@@ -25,7 +25,8 @@ export class Tenants extends APIResource {
   templates: TemplatesAPI.Templates = new TemplatesAPI.Templates(this._client);
 
   /**
-   * Get a Tenant
+   * Returns one tenant with its name, parent tenant id, default preferences,
+   * properties, and the user profile applied to its members.
    *
    * @example
    * ```ts
@@ -37,7 +38,8 @@ export class Tenants extends APIResource {
   }
 
   /**
-   * Create or Replace a Tenant
+   * Creates or replaces a tenant from a name, parent, brand, properties, and default
+   * preferences supplied in the request body.
    *
    * @example
    * ```ts
@@ -51,7 +53,8 @@ export class Tenants extends APIResource {
   }
 
   /**
-   * Get a List of Tenants
+   * Lists the workspace's tenants, each carrying a name, parent tenant, properties,
+   * and default preferences. Paged.
    *
    * @example
    * ```ts
@@ -66,7 +69,8 @@ export class Tenants extends APIResource {
   }
 
   /**
-   * Delete a Tenant
+   * Deletes a tenant. Its members' workspace-level profiles and preferences live
+   * outside the tenant and are managed separately.
    *
    * @example
    * ```ts
@@ -81,7 +85,8 @@ export class Tenants extends APIResource {
   }
 
   /**
-   * Get Users in Tenant
+   * Returns the users belonging to a tenant with cursor paging. Use it to see who a
+   * tenant-scoped send will reach.
    *
    * @example
    * ```ts
diff --git a/src/resources/translations.ts b/src/resources/translations.ts
index ac89f265..db04387e 100644
--- a/src/resources/translations.ts
+++ b/src/resources/translations.ts
@@ -8,7 +8,8 @@ import { path } from '../internal/utils/path';
 
 export class Translations extends APIResource {
   /**
-   * Get translations by locale
+   * Returns the translation strings stored for one domain and locale, for use in
+   * localized notification content.
    */
   retrieve(locale: string, params: TranslationRetrieveParams, options?: RequestOptions): APIPromise<string> {
     const { domain } = params;
@@ -16,7 +17,8 @@ export class Translations extends APIResource {
   }
 
   /**
-   * Update a translation
+   * Uploads the translation strings for one domain and locale. Courier uses them to
+   * render localized content for recipients in that locale.
    */
   update(locale: string, params: TranslationUpdateParams, options?: RequestOptions): APIPromise<void> {
     const { domain, body } = params;
diff --git a/src/resources/users/preferences.ts b/src/resources/users/preferences.ts
index decc3128..ab2d9efb 100644
--- a/src/resources/users/preferences.ts
+++ b/src/resources/users/preferences.ts
@@ -9,7 +9,8 @@ import { path } from '../../internal/utils/path';
 
 export class Preferences extends APIResource {
   /**
-   * Fetch all user preferences.
+   * Returns a user's preference overrides with paging, one entry per subscription
+   * topic they have set a choice for.
    *
    * @example
    * ```ts
@@ -27,23 +28,8 @@ export class Preferences extends APIResource {
   }
 
   /**
-   * Replace a user's complete set of preference overrides in a single request. The
-   * topics in the request body become the recipient's entire set of overrides:
-   * listed topics are created or updated, and every existing override that is not
-   * included in the body is reset to its topic default. Submitting an empty `topics`
-   * array is a valid clear-all that resets every existing override.
-   *
-   * This operation is validation-atomic (all-or-nothing): structural validation
-   * fails fast with a single `400`, and if any topic is semantically invalid (an
-   * unknown topic, a `REQUIRED` topic that cannot be opted out, or a custom routing
-   * request that is not available on the workspace's plan) the request returns a
-   * single `400` aggregating every failure in `errors` and writes nothing. On
-   * success it returns `200` with `items` (the complete resulting override set) and
-   * `deleted` (the ids of the overrides that were reset to default).
-   *
-   * Every `topic_id` in the response — in `items`, `deleted`, and any `errors` — is
-   * returned in Courier's canonical topic id form, regardless of the form supplied
-   * in the request.
+   * Replaces a user's entire set of preference overrides. Any topic you leave out is
+   * reset to its default, so send the full set rather than a subset.
    *
    * @example
    * ```ts
@@ -72,23 +58,8 @@ export class Preferences extends APIResource {
   }
 
   /**
-   * Additively create or update a user's preferences for one or more subscription
-   * topics in a single request. Only the topics included in the request body are
-   * created or updated; any existing overrides for topics not listed are left
-   * untouched.
-   *
-   * Structural validation of the request body fails fast with a single `400`. Beyond
-   * that, each topic is processed independently (partial-success, not
-   * all-or-nothing): valid topics are written and returned in `items`, while topics
-   * that cannot be applied are collected in `errors` with a per-topic `reason` (for
-   * example an unknown topic, a `REQUIRED` topic that cannot be opted out, a custom
-   * routing request that is not available on the workspace's plan, or a write
-   * failure). The request therefore returns `200` with both lists whenever the body
-   * is structurally valid.
-   *
-   * Every `topic_id` in the response — in both `items` and `errors` — is returned in
-   * Courier's canonical topic id form, regardless of the form supplied in the
-   * request.
+   * Adds or updates a user's preferences for several subscription topics at once.
+   * Topics you leave out keep whatever they were set to before.
    *
    * @example
    * ```ts
@@ -121,9 +92,8 @@ export class Preferences extends APIResource {
   }
 
   /**
-   * Remove a user's preferences for a specific subscription topic, resetting the
-   * topic to its effective default. This operation is idempotent: deleting a
-   * preference that does not exist succeeds with no error.
+   * Removes a user's override for one subscription topic, resetting it to the
+   * effective default from the tenant or workspace.
    *
    * @example
    * ```ts
@@ -146,7 +116,8 @@ export class Preferences extends APIResource {
   }
 
   /**
-   * Fetch user preferences for a specific subscription topic.
+   * Returns a user's opt-in status and channel choices for one subscription topic,
+   * or the effective default if they have set no override.
    *
    * @example
    * ```ts
@@ -166,7 +137,8 @@ export class Preferences extends APIResource {
   }
 
   /**
-   * Update or Create user preferences for a specific subscription topic.
+   * Sets a user's opt-in status and channel choices for one subscription topic,
+   * overriding the tenant default for that topic only.
    *
    * @example
    * ```ts
@@ -216,19 +188,40 @@ export interface BulkPreferenceTopic {
 }
 
 export interface TopicPreference {
+  /**
+   * The topic's default status, returned on reads. It applies whenever the user has
+   * no override of their own (status equals this value).
+   */
   default_status: Shared.PreferenceStatus;
 
+  /**
+   * The user's subscription status for this topic. OPTED_IN or OPTED_OUT reflect the
+   * user's own choice; REQUIRED is a topic-level default set in the preferences
+   * editor, not a user choice.
+   */
   status: Shared.PreferenceStatus;
 
+  /**
+   * The unique identifier of the subscription topic this preference applies to.
+   */
   topic_id: string;
 
+  /**
+   * The display name of the subscription topic, returned on reads.
+   */
   topic_name: string;
 
   /**
-   * The Channels a user has chosen to receive notifications through for this topic
+   * The channels the user has chosen to receive this topic on, present only when
+   * has_custom_routing is true. One or more of: direct_message, email, push, sms,
+   * webhook, inbox.
    */
   custom_routing?: Array<Shared.ChannelClassification> | null;
 
+  /**
+   * Whether the user has chosen specific delivery channels for this topic (listed in
+   * custom_routing) rather than the topic's default routing.
+   */
   has_custom_routing?: boolean | null;
 }
 
@@ -418,13 +411,23 @@ export interface PreferenceUpdateOrCreateTopicParams {
 
 export namespace PreferenceUpdateOrCreateTopicParams {
   export interface Topic {
+    /**
+     * The subscription status to set: OPTED_IN or OPTED_OUT. REQUIRED is a topic-level
+     * default, not a user choice; the API rejects opting a user out of a REQUIRED
+     * topic.
+     */
     status: Shared.PreferenceStatus;
 
     /**
-     * The Channels a user has chosen to receive notifications through for this topic
+     * The channels to deliver this topic on when has_custom_routing is true. One or
+     * more of: direct_message, email, push, sms, webhook, inbox.
      */
     custom_routing?: Array<Shared.ChannelClassification> | null;
 
+    /**
+     * Set to true to route this topic to the channels in custom_routing instead of the
+     * topic's default routing.
+     */
     has_custom_routing?: boolean | null;
   }
 }
diff --git a/src/resources/users/tenants.ts b/src/resources/users/tenants.ts
index b68b7e02..ca304295 100644
--- a/src/resources/users/tenants.ts
+++ b/src/resources/users/tenants.ts
@@ -9,7 +9,8 @@ import { path } from '../../internal/utils/path';
 
 export class Tenants extends APIResource {
   /**
-   * Returns a paginated list of user tenant associations.
+   * Returns the tenants a user belongs to, with cursor paging. A user can belong to
+   * many tenants, each with its own profile and preferences.
    *
    * @example
    * ```ts
@@ -25,9 +26,8 @@ export class Tenants extends APIResource {
   }
 
   /**
-   * This endpoint is used to add a user to multiple tenants in one call. A custom
-   * profile can also be supplied for each tenant. This profile will be merged with
-   * the user's main profile when sending to the user with that tenant.
+   * Adds a user to several tenants in one call, each optionally with a per-tenant
+   * profile that overrides their workspace profile.
    *
    * @example
    * ```ts
@@ -45,10 +45,8 @@ export class Tenants extends APIResource {
   }
 
   /**
-   * This endpoint is used to add a single tenant.
-   *
-   * A custom profile can also be supplied with the tenant. This profile will be
-   * merged with the user's main profile when sending to the user with that tenant.
+   * Adds a user to one tenant, optionally with a tenant-specific profile that
+   * overrides their workspace profile for sends in that tenant.
    *
    * @example
    * ```ts
@@ -67,7 +65,8 @@ export class Tenants extends APIResource {
   }
 
   /**
-   * Removes a user from any tenants they may have been associated with.
+   * Removes a user from every tenant they belong to in one call. Their
+   * workspace-level profile is a separate resource.
    *
    * @example
    * ```ts
@@ -82,7 +81,8 @@ export class Tenants extends APIResource {
   }
 
   /**
-   * Removes a user from the supplied tenant.
+   * Removes a user from one tenant. Their other tenant memberships and workspace
+   * profile are managed through separate endpoints.
    *
    * @example
    * ```ts
diff --git a/src/resources/users/tokens.ts b/src/resources/users/tokens.ts
index 1e0c15fb..68a6d197 100644
--- a/src/resources/users/tokens.ts
+++ b/src/resources/users/tokens.ts
@@ -8,7 +8,8 @@ import { path } from '../../internal/utils/path';
 
 export class Tokens extends APIResource {
   /**
-   * Get single token available for a `:token`
+   * Returns one device token with its provider key, status and status reason, expiry
+   * date, and any properties stored alongside it.
    *
    * @example
    * ```ts
@@ -27,7 +28,8 @@ export class Tokens extends APIResource {
   }
 
   /**
-   * Apply a JSON Patch (RFC 6902) to the specified token.
+   * Applies a JSON Patch to a device token, changing its status, expiry, or
+   * properties without re-registering it.
    *
    * @example
    * ```ts
@@ -47,7 +49,8 @@ export class Tokens extends APIResource {
   }
 
   /**
-   * Gets all tokens available for a :user_id
+   * Returns every device token registered for a user, each with its provider key,
+   * status, and expiry date.
    *
    * @example
    * ```ts
@@ -59,7 +62,8 @@ export class Tokens extends APIResource {
   }
 
   /**
-   * Delete User Token
+   * Deletes one device token for a user, addressed by the token value, so push sends
+   * no longer target that device.
    *
    * @example
    * ```ts
@@ -77,7 +81,8 @@ export class Tokens extends APIResource {
   }
 
   /**
-   * Adds multiple tokens to a user and overwrites matching existing tokens.
+   * Registers several device tokens for a user in one call, overwriting any stored
+   * token with a matching value.
    *
    * @example
    * ```ts
@@ -92,7 +97,8 @@ export class Tokens extends APIResource {
   }
 
   /**
-   * Adds a single token to a user and overwrites a matching existing token.
+   * Registers one device token for a user against a provider key, overwriting the
+   * token if it already exists. Push sends resolve tokens per user.
    *
    * @example
    * ```ts
diff --git a/src/resources/workspace-preferences/topics.ts b/src/resources/workspace-preferences/topics.ts
index 420db23b..de55f090 100644
--- a/src/resources/workspace-preferences/topics.ts
+++ b/src/resources/workspace-preferences/topics.ts
@@ -10,9 +10,8 @@ import { path } from '../../internal/utils/path';
 
 export class Topics extends APIResource {
   /**
-   * Create a subscription preference topic inside a workspace preference. Fails with
-   * 404 if the workspace preference does not exist. The topic id is generated and
-   * returned.
+   * Creates a subscription topic inside a workspace preference. The default status
+   * sets whether users start opted in, opted out, or required.
    *
    * @example
    * ```ts
@@ -32,9 +31,8 @@ export class Topics extends APIResource {
   }
 
   /**
-   * Retrieve a topic within a workspace preference. Returns 404 if the workspace
-   * preference does not exist, the topic does not exist, or the topic belongs to a
-   * different workspace preference.
+   * Returns one subscription topic with its default status, routing options, allowed
+   * preferences, and unsubscribe header setting.
    *
    * @example
    * ```ts
@@ -55,7 +53,8 @@ export class Topics extends APIResource {
   }
 
   /**
-   * List the topics in a workspace preference.
+   * Returns the subscription topics inside a workspace preference, each with its
+   * default status and routing options.
    *
    * @example
    * ```ts
@@ -73,8 +72,8 @@ export class Topics extends APIResource {
   }
 
   /**
-   * Archive a topic and remove it from its workspace preference. Same 404 rules as
-   * GET.
+   * Archives a subscription topic and removes it from its workspace preference,
+   * addressed by section id and topic id.
    *
    * @example
    * ```ts
diff --git a/src/resources/workspace-preferences/workspace-preferences.ts b/src/resources/workspace-preferences/workspace-preferences.ts
index e33e4f0e..dc2c33f2 100644
--- a/src/resources/workspace-preferences/workspace-preferences.ts
+++ b/src/resources/workspace-preferences/workspace-preferences.ts
@@ -19,9 +19,8 @@ export class WorkspacePreferences extends APIResource {
   topics: TopicsAPI.Topics = new TopicsAPI.Topics(this._client);
 
   /**
-   * Create a workspace preference. The workspace preference id is generated and
-   * returned. Topics are created inside a workspace preference via POST
-   * /preferences/sections/{section_id}/topics.
+   * Creates a workspace preference and returns its generated id. Add subscription
+   * topics to it afterwards with the topics endpoint.
    *
    * @example
    * ```ts
@@ -39,7 +38,8 @@ export class WorkspacePreferences extends APIResource {
   }
 
   /**
-   * Retrieve a workspace preference by id, including its topics.
+   * Returns one workspace preference by id, including its subscription topics,
+   * routing options, and custom routing flag.
    *
    * @example
    * ```ts
@@ -52,8 +52,8 @@ export class WorkspacePreferences extends APIResource {
   }
 
   /**
-   * List the workspace's preferences. Each workspace preference embeds its topics.
-   * Scoped to the workspace of the API key.
+   * Returns the workspace's preferences, each embedding its subscription topics,
+   * routing options, and whether custom routing is allowed.
    *
    * @example
    * ```ts
@@ -82,9 +82,8 @@ export class WorkspacePreferences extends APIResource {
   }
 
   /**
-   * Publish the workspace's preferences page. Takes a snapshot of every workspace
-   * preference with its topics under a new published version, making the current
-   * state visible on the hosted preferences page (non-draft).
+   * Publishes the workspace preference page, snapshotting every preference and
+   * topic, and returns the page id and a preview URL.
    *
    * @example
    * ```ts
diff --git a/src/version.ts b/src/version.ts
index 709152b6..236ed920 100644
--- a/src/version.ts
+++ b/src/version.ts
@@ -1 +1 @@
-export const VERSION = '7.21.0'; // x-release-please-version
+export const VERSION = '7.21.1'; // x-release-please-version