Assistant message tiers

ai/assistant.mdx

@@ -12,13 +12,15 @@
 
 The assistant answers questions about your documentation through natural language queries. Users access the assistant on your documentation site, so they can find answers quickly and succeed with your product even if they don't know where to look.
 
 The assistant uses agentic RAG (retrieval-augmented generation) with tool calling powered by Claude Opus 4.5. When users ask questions, the assistant:
 
 * **Searches and retrieves** relevant content from your documentation to provide accurate answers.
 * **Cites sources** and provides navigable links to take users directly to referenced pages.
 * **Generates copyable code examples** to help users implement solutions from your documentation.
 
-Each message sent to the assistant counts toward your plan's message allowance. If you exceed your allowance, additional messages incur overage charges. You can set spending limits or disable the assistant if you reach your message allowance.
+The assistant uses tiered message allowances. A message is any user interaction with the assistant that receives a correct response. If you have unused messages, up to half of your message allowance can carry over to the next billing cycle. For example, if you have a 1,000 message allowance and you use 300 messages, 500 messages carry over to the next billing cycle giving you a total of 1,500 messages for the next billing cycle.
+
+By default, the assistant does not allow overages. If you reach your message allowance, the assistant is unavailable until your message allowance resets. You can allow overages to continue using the assistant. Each additional message incurs an overage charge, but occasional overages may be cheaper than upgrading to a higher tier depending on your usage.
 
 You can view assistant usage through your dashboard to understand user behavior and documentation effectiveness. Export and analyze query data to help identify:
 
@@ -42,16 +44,11 @@
 
 The assistant is active on Pro and Custom plans by default.
 
-Manage the assistant from your [dashboard](https://dashboard.mintlify.com/products/assistant/settings). Click **Configuration** to enable or disable the assistant, configure response handling, add default questions, and set a spend limit.
-
-<Frame>
-  <img src="/images/assistant/configuration-light.png" alt="The assistant toolbar in the dashboard. The Configuration button is emphasized with an orange rectangle." className="block dark:hidden" />
-  <img src="/images/assistant/configuration-dark.png" alt="The assistant toolbar in the dashboard. The Configuration button is emphasized with an orange rectangle." className="hidden dark:block" />
-</Frame>
+Manage the assistant from the [Assistant Configurations](https://dashboard.mintlify.com/products/assistant/settings) page of your dashboard. Enable or disable the assistant, configure response handling, add default questions, and manage your message allowance.
 
 ### Enable or disable the assistant
 
 Toggle the assistant status to enable or disable the assistant for your documentation site.
 
 <Frame>
   <img src="/images/assistant/status-light.png" alt="The assistant status toggle in the dashboard." className="block dark:hidden" />
@@ -112,18 +109,17 @@
   </Frame>
 2. In the **Spending Controls** section, select your preferred tier from the dropdown menu.
 
-**Upgrading your tier:**
+**Upgrade your tier:**
 - Your new message allowance is available immediately.
 - You pay a prorated difference for the current billing cycle.
 
-**Downgrading your tier:**
-- Your new message allowance takes effect immediately.
-- Unused messages from your current tier do not carry over.
+**Downgrade your tier:**
+- Your message allowance updates immediately.
+- Pricing changes take effect at the start of your next billing cycle.
+- Unused messages from your current tier **do not** carry over.
 
 ### Allow overages
 
-By default, the assistant does not allow overages. If you reach your message allowance, the assistant is unavailable until your message allowance resets.
-
 If you want to allow overages, enable them in the **Billing Controls** section of the [Assistant Configurations](https://dashboard.mintlify.com/products/assistant/settings/billing) page of your dashboard.
 
 You can also set usage alerts to receive an email when you reach a certain percentage of your message allowance.