Improve AI Coding Assistant docs (#3197)

* docs(AI): Add usage tips and recommendations

* Rename Number of Requests heading

* Clarify # usage for VS Code

Author: dimodi

_contentTemplates/common/ai-coding-assistant.md

@@ -1,5 +1,5 @@
 #number-of-requests
-A Telerik [Subscription license](https://www.telerik.com/purchase/faq/licensing-purchasing) is recommended in order to use the Telerik Blazor AI Coding Assistant without restrictions. Perpetual license holders and trial users can make a [limited number of requests per year](slug:ai-overview#number-of-requests).
+A Telerik [Subscription license](https://www.telerik.com/purchase/faq/licensing-purchasing) is recommended in order to use the Telerik Blazor AI Coding Assistant without restrictions. Perpetual license holders and trial users can make a [limited number of requests per year](slug:ai-overview#usage-limits).
 #end
 
 #vs-intro

ai/copilot-extension.md

@@ -22,6 +22,8 @@ To use the Telerik GitHub Copilot extension for Blazor, you need to have:
 * A [Blazor application that includes Telerik UI for Blazor](slug:blazor-overview#getting-started).
 * Using the latest version of your [Copilot-enabled app](https://docs.github.com/en/copilot/building-copilot-extensions/about-building-copilot-extensions#supported-clients-and-ides) is recommended (for example, Visual Studio or VS Code).
 
+Check [AI Coding Assistant Overview](slug:ai-overview) for more recommendations and usage information.
+
 ## Installation
 
 To install the Telerik Blazor Copilot extension:
@@ -46,7 +48,8 @@ To use the Telerik Blazor Copilot extension:
 1. Start your prompt with `@telerikblazor` and type your request. Make sure that `@telerikblazor` is recognized and highlighted, otherwise the extension may not be installed.
 1. Verify that you see a label similar to **TelerikBlazor working...** or **TelerikBlazor generating response...** in the output.
 1. Grant permission to the Telerik Blazor extension to read your workspace files.
-1. If you want to prompt for information or code that are not related to your previous prompts, it is a good practice to start a new session in a new chat window, so that the context is not polluted by irrelevant old information.
+
+Also check the general [AI Coding Assistant Recommendations](slug:ai-overview#recommendations) for more usage tips.
 
 ### Sample Prompts
 
@@ -56,7 +59,7 @@ The following list describes how your prompts may look like:
 * "`@telerikblazor` Generate a Telerik ComboBox for Blazor that shows a list of products. Create a Product class and generate sample data."
 * "`@telerikblazor` Show me sample code for a Telerik Blazor Grid with virtual scrolling for the rows and columns."
 
-## Number of Requests
+## Usage Limits
 
 @[template](/_contentTemplates/common/ai-coding-assistant.md#number-of-requests)
 

ai/mcp-server.md

@@ -22,6 +22,8 @@ To use the Telerik Blazor MCP server, you need:
 * An active [DevCraft or Telerik UI for Blazor license](https://www.telerik.com/purchase/blazor-ui) or a [Telerik UI for Blazor trial](https://www.telerik.com/blazor-ui).
 * A [Blazor application that includes Telerik UI for Blazor](slug:blazor-overview#getting-started).
 
+Check [AI Coding Assistant Overview](slug:ai-overview) for more recommendations and usage information.
+
 ## Installation
 
 There are two ways to install the Telerik Blazor MCP server:
@@ -141,24 +143,21 @@ To [enable the Telerik MCP Server in a specific workspace, Blazor app, or global
 
 ## Usage
 
+By default, MCP clients do not call MCP tools in a deterministic way. Some MCP clients like [VS Code](#vs-code) allow you to explicitly reference the desired MCP tool in your prompt.
+
 To use the Telerik MCP Server:
 
-1. Start your prompt with one of the following:
-    * `telerik`
-    * `/telerik`
-    * `@telerik`
-    * `telerikblazor`
-    * `/telerikblazor`
-    * `@telerikblazor`
-1. Confirm that the Telerik MCP server is used, because this doesn't happen deterministically. Look for a statement in the output, which is similar to:
-    * `Running telerikBlazorAssistant` (in VS Code)
-    * `Calling MCP tool telerikBlazorAssistant` (in Cursor)
+1. Start your prompt with `Telerik` to make it more likely for the Telerik MCP server to get called. If you are using VS Code, then start your prompt with:
+    * `#` and the MCP server name that you used in `mcp.json` (for example, `#telerikBlazorAssistant`)
+    * `#` and the name of the Telerik Blazor MCP tool (`#telerik_blazor_assistant`)
+1. Confirm that the Telerik MCP server is used. Look for a statement in the output, which is similar to:
+    * `Running telerik_blazor_assistant` (in VS Code)
+    * `Calling MCP tool telerik_blazor_assistant` (in Cursor)
+1. Grant the Telerik tool permission to run for the current session, workspace, or always.
 
-    If the Telerik MCP server is not used even though it's installed and enabled, then try rephrasing your prompt and use another trigger syntax from the list in step 1.
-1. Grant the Telerik tool permission to run for this session, workspace, or always.
-1. If you want to prompt for information or code that are not related to your previous prompts, it is a good practice to start a new session in a new chat window, so that the context is not polluted by irrelevant old information.
+Also check the general [AI Coding Assistant Recommendations](slug:ai-overview#recommendations) for more usage tips.
 
-To increase the probability of the Telerik MCP Server being used, or to call it without the need to mention "telerik" explicitly, add custom instructions to your AI-powered tool. Here are examples for [GitHub Copilot](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot#about-repository-custom-instructions-for-github-copilot-chat) and [Cursor](https://docs.cursor.com/context/rules).
+To call the Telerik MCP server without the need to type `Telerik` or `#telerikBlazorAssistant` explicitly, add custom instructions to your AI-powered tool. Here are examples for [GitHub Copilot](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot#about-repository-custom-instructions-for-github-copilot-chat) and [Cursor](https://docs.cursor.com/context/rules).
 
 ### Sample Prompts
 
@@ -168,7 +167,7 @@ The following list describes how your prompts may look like:
 * "Telerik Generate a ComboBox for Blazor that shows a list of products. Create a Product class and generate sample data."
 * "Telerik Show me sample code for a Blazor Grid with virtual scrolling for the rows and columns."
 
-## Number of Requests
+## Usage Limits
 
 @[template](/_contentTemplates/common/ai-coding-assistant.md#number-of-requests)
 

ai/overview.md

@@ -31,11 +31,37 @@ To use the Telerik Blazor AI Coding Assistant, you need:
 * A [Blazor application that includes Telerik UI for Blazor](slug:blazor-overview#getting-started).
 * @[template](/_contentTemplates/common/ai-coding-assistant.md#number-of-requests)
 
-## Number of Requests
+## Intended Use
+
+You can use the Telerik AI Coding Assistant for:
+
+* Initial code generation: Quickly add components to your app to speed up the initial development.
+* Component configuration: Enable or disable specific component features, or fine tune the configuration through prompting. More complex configurations are possible but may require additional manual work to be production-ready.
+* Dummy data generation and data binding: Quickly add data to your app for testing and prototyping purposes. Avoid exposing or providing access to your proprietary or production data to AI-enabled tools.
+* Step-by-step explanations: Understand the solutions provided by the AI Coding Assistant through the detailed explanations (depends on the tool, mode, and model). To further develop your knowledge, check the respective documentation.
+* Preliminary troubleshooting: Resolve obvious and easy-to-solve issues affecting your code. For more complex issues, search the product documentation or look for assistance from the community.
+
+>warning Always double-check the suggested code and solutions of any AI-powered tool before applying them to your app.
+
+> The Telerik AI Coding Assistant is not intended for styling and theme customization. If you are looking for AI-powered styling and theming, check out [Telerik ThemeBuilder](https://www.telerik.com/themebuilder).
+
+## Recommendations
+
+Consider the following recommendations when working with the Telerik AI Coding Assistant:
+
+* When switching between tasks and files, start a new session in a new chat window to avoid polluting the context with irrelevant or outdated information.
+* At the time of publishing, Claude Sonnet 4 and GPT-5 produce better results.
+* Sometimes, the AI Coding Assistant might generate custom styles. To avoid any custom styling, include a similar statement in your prompts: `Don't add custom CSS styles`.
+
+## Telerik Document Processing AI Coding Assistant
+
+You can also use the AI Coding Assistant for [Telerik Document Processing](https://www.telerik.com/document-processing-libraries) to generate high-quality code samples and speed up your development. Read the full guide in the dedicated [DPL AI Coding Assistant](https://docs.telerik.com/devtools/document-processing/ai-coding-assistant/overview) article.
+
+## Usage Limits
 
 The Telerik Blazor AI Conding Assistant allows the following maximum number of requests, depending on your [Telerik license type](https://www.telerik.com/purchase/faq/licensing-purchasing):
 
-* Perpetual licenses: 50 requests per year
+* Perpetual licenses: include 50 requests per year to let you explore and try out the AI Coding Assistant. If you'd like ongoing, higher-volume access, switch to a Subscription license.
 * Subscription licenses: virtually unlimited number of requests with a fair use threshold of 300 requests per day
 * Trial licenses: 300 requests per trial per year. Activating the same trial for a new release does not grant additional 300 requests.
 
@@ -50,7 +76,7 @@ The Telerik Blazor AI Coding Assistant operates under the following conditions:
 * The Assistant does not use your prompts to train Telerik AI models.
 * The Assistant does not generate the actual responses and has no access to these responses. The Assistant only provides a better context that helps your selected model (for example, GPT, Gemini, Claude) provide better responses.
 * The Assistant does not associate your prompts to your Telerik user account. Your prompts and generated context are anonymized and stored for statistical and troubleshooting purposes.
-* The Assistant stores metrics about how often and how much you use it in order to ensure compliance with the [allowed number of requests that correspond to your current license](#number-of-requests).
+* The Assistant stores metrics about how often and how much you use it in order to ensure compliance with the [allowed number of requests that correspond to your current license](#usage-limits).
 
 Make sure to also get familiar with the terms and privacy policy of your selected AI model and AI client.