LibreChat-AI · danny-avila · Jun 8, 2026 · Jun 8, 2026 · Jun 8, 2026 · Jun 8, 2026
diff --git a/content/docs/configuration/index.mdx b/content/docs/configuration/index.mdx
@@ -6,6 +6,18 @@ description: How LibreChat's configuration files work together and how to apply
 
 LibreChat uses four main configuration files. Each controls a different aspect of the application -- from environment variables to custom AI endpoints to Docker service overrides.
 
+## Common Change Workflow
+
+Most configuration changes follow the same pattern:
+
+1. Edit `.env` for secrets, API keys, and server-level feature flags.
+2. Edit `librechat.yaml` for custom endpoints, model specs, interface settings, MCP servers, agents, and advanced app behavior.
+3. For Docker, make sure `librechat.yaml` is mounted through `docker-compose.override.yml` before expecting LibreChat to read it.
+4. Restart LibreChat after every configuration change.
+5. Check the API logs if the change does not appear in the UI.
+
+For example, to enable OpenRouter you add `OPENROUTER_KEY` to `.env`, add an OpenRouter endpoint in `librechat.yaml`, make sure Docker mounts `librechat.yaml`, restart, then select OpenRouter from the endpoint selector.
+
 ## Configuration Files
 
 <FileTree>

diff --git a/content/docs/configuration/librechat_yaml/ai_endpoints/openrouter.mdx b/content/docs/configuration/librechat_yaml/ai_endpoints/openrouter.mdx
@@ -115,6 +115,28 @@ docker compose logs api | grep -i "error\|openrouter"
   </Step>
 </Steps>
 
+## Troubleshooting
+
+### OpenRouter Does Not Appear in the Model Selector
+
+Check these items in order:
+
+1. `OPENROUTER_KEY` is set in `.env`.
+2. `librechat.yaml` contains the OpenRouter entry under `endpoints.custom`.
+3. Docker users have mounted `librechat.yaml` in `docker-compose.override.yml`.
+4. LibreChat was restarted after editing both files.
+5. The API logs do not show YAML validation errors.
+
+```bash
+docker compose logs api
+```
+
+If the logs mention a missing environment variable, check that the variable name in `.env` matches the variable referenced in `librechat.yaml`. For this guide, that means `apiKey: "${OPENROUTER_KEY}"` in `librechat.yaml` and `OPENROUTER_KEY=...` in `.env`.
+
+### OpenRouter Returns 402 Payment Required
+
+A `402 Payment Required` response comes from OpenRouter, not LibreChat. Add credits or choose a free/available model in OpenRouter, then retry the same endpoint in LibreChat.
+
 ## Customization
 
 ### Using user_provided API Key

diff --git a/content/docs/configuration/librechat_yaml/index.mdx b/content/docs/configuration/librechat_yaml/index.mdx
@@ -10,6 +10,12 @@ The `librechat.yaml` file is LibreChat's main configuration file for custom AI e
 
 Follow the steps below to create the file, mount it for your deployment type, and verify it works.
 
+<Callout type="info" title="If you only remember one thing">
+
+For Docker installs, editing `librechat.yaml` is not enough. The file must exist in the project root, be mounted into the API container, and LibreChat must be restarted before changes appear in the UI.
+
+</Callout>
+
 ## Setup
 
 <Steps>
@@ -172,6 +178,18 @@ For detailed field-level documentation, see the reference pages below.
 
 ## Troubleshooting
 
+### Change Does Not Show in LibreChat
+
+If you edited `librechat.yaml` and nothing changed in the UI:
+
+1. Confirm the file is in the LibreChat project root unless you set `CONFIG_PATH`.
+2. For Docker, confirm the file is mounted in `docker-compose.override.yml`.
+3. Restart LibreChat with `docker compose down && docker compose up -d`.
+4. Check the API logs with `docker compose logs api`.
+5. Validate the file with the [YAML Validator](/toolkit/yaml_checker).
+
+Custom endpoints such as OpenRouter only appear after all three pieces are correct: `.env` contains the key, `librechat.yaml` defines the endpoint, and Docker can read the mounted config file.
+
 ### Configuration Validation
 
 <Callout type="error" title="Configuration Validation">

diff --git a/content/docs/configuration/tools/azure_ai_search.mdx b/content/docs/configuration/tools/azure_ai_search.mdx
@@ -3,20 +3,19 @@ title: Azure AI Search
 icon: Radar
 description: How to configure Azure AI Search for answers to your questions with assistance from GPT.
 ---
-Through the plugins endpoint, you can use Azure AI Search for answers to your questions with assistance from GPT.
+Azure AI Search is a built-in agent tool that lets an agent query your Azure AI Search index and use the returned documents in its answer.
 
-## Configurations
+## Configuration
 
 ### Required
 
-To get started, you need to get a Azure AI Search endpoint URL, index name, and a API Key. You can then define these as follows in your `.env` file:
+To get started, you need an Azure AI Search endpoint URL, index name, and API key. Define them in your `.env` file:
 
 ```env
 AZURE_AI_SEARCH_SERVICE_ENDPOINT="..."
 AZURE_AI_SEARCH_INDEX_NAME="..."
 AZURE_AI_SEARCH_API_KEY="..."
 ```
-Or you need to get an Azure AI Search endpoint URL, index name, and an API Key. You can define them during the installation of the plugin.
 
 ### AZURE_AI_SEARCH_SERVICE_ENDPOINT
 
@@ -96,21 +95,23 @@ Now select the free option or select your preferred option (may incur charges).
 
 ![image](/images/azure-ai-search/azure_ai_search_keys.png)
 
-# Configure in LibreChat:
+## Add the Tool to an Agent
 
-**1.** Access the Plugins and click to install Azure AI Search.
+After adding the environment variables, restart LibreChat and add **Azure AI Search** to an agent.
 
-![image](/images/azure-ai-search/librechat_settings.png)
+| Deployment | Command |
+|------------|---------|
+| Docker | `docker compose down && docker compose up -d` |
+| Local | Stop the server, then run `npm run backend` again |
 
+In LibreChat, select **Agents**, create or edit an agent, open the agent's **Tools** list, select **Azure AI Search**, and save the agent.
 
-**2.** Fill in the Endpoint, Index Name, and API Key, and click on `Save`.
+## Test It
 
-# Conclusion
+Ask the agent a question that should be answered by your Azure AI Search index. If the tool returns too much content, tune `AZURE_AI_SEARCH_SEARCH_OPTION_TOP` and `AZURE_AI_SEARCH_SEARCH_OPTION_SELECT`.
 
 ![image](/images/azure-ai-search/chat_with_azure_ai_search.png)
 
-Now, you will be able to conduct searches using Azure AI Search. Congratulations! 🎉🎉
-
 ## Optional
 
 The following are configuration values that are not required but can be specified as parameters during a search.

diff --git a/content/docs/configuration/tools/calculator.mdx b/content/docs/configuration/tools/calculator.mdx
@@ -0,0 +1,34 @@
+---
+title: Calculator
+icon: Calculator
+description: Use the built-in Calculator tool in LibreChat agents
+---
+
+Calculator is a built-in agent tool for arithmetic and symbolic calculations. It does not require an API key or environment variable.
+
+## Setup
+
+<Steps>
+  <Step>
+
+### Add Calculator to an Agent
+
+In LibreChat, select **Agents**, create or edit an agent, open the agent's **Tools** list, select **Calculator**, and save the agent.
+
+  </Step>
+  <Step>
+
+### Test It
+
+Ask the agent to calculate something that benefits from a tool call:
+
+```text
+Calculate 12345 * 6789 and show the result.
+```
+
+  </Step>
+</Steps>
+
+## Troubleshooting
+
+If Calculator is not visible in the Agent Builder, check whether your `librechat.yaml` uses [`includedTools`](/docs/configuration/librechat_yaml/object_structure/config#includedtools) or [`filteredTools`](/docs/configuration/librechat_yaml/object_structure/config#filteredtools).
diff --git a/content/docs/configuration/tools/flux.mdx b/content/docs/configuration/tools/flux.mdx
@@ -10,10 +10,18 @@ Flux is a powerful image generation tool that can create high-quality images fro
 
 1. Get your API key from [bfl.ml](https://bfl.ml)
 2. Set the `FLUX_API_KEY` environment variable in your `.env` file:
+
 ```bash
 FLUX_API_KEY=your_api_key_here
 ```
 
+3. Restart LibreChat and add **Flux** to an agent's **Tools** list.
+
+| Deployment | Command |
+|------------|---------|
+| Docker | `docker compose down && docker compose up -d` |
+| Local | Stop the server, then run `npm run backend` again |
+
 ## Features
 
 ### Core Capabilities

diff --git a/content/docs/configuration/tools/gemini_image_gen.mdx b/content/docs/configuration/tools/gemini_image_gen.mdx
@@ -35,6 +35,13 @@ GOOGLE_CLOUD_LOCATION=us-central1
 
 When no `GEMINI_API_KEY` or `GOOGLE_KEY` is configured, the tool automatically falls back to Vertex AI using the service account file.
 
+After configuring credentials, restart LibreChat and add **Gemini Image Tools** to an agent's **Tools** list.
+
+| Deployment | Command |
+|------------|---------|
+| Docker | `docker compose down && docker compose up -d` |
+| Local | Stop the server, then run `npm run backend` again |
+
 ## Configuration Options
 
 ### Model Selection
@@ -151,4 +158,3 @@ Rate limits depend on your API tier:
 
 - **Gemini API**: Check [Google AI Studio](https://aistudio.google.com/) for current limits
 - **Vertex AI**: Based on your Google Cloud project quotas
-
diff --git a/content/docs/configuration/tools/google_search.mdx b/content/docs/configuration/tools/google_search.mdx
@@ -6,7 +6,7 @@ description: Set up Google Custom Search as an agent tool in LibreChat
 
 <Callout type="info" title="Looking for Web Search?">
 
-This page covers the **Google Custom Search** tool (agent plugin). For LibreChat's built-in **Web Search** feature (Serper/SearXNG + Firecrawl + Jina), see [Web Search](/docs/features/web_search).
+This page covers the **Google Custom Search** agent tool. For LibreChat's built-in **Web Search** feature (Serper/SearXNG + Firecrawl + Jina), see [Web Search](/docs/features/web_search).
 
 </Callout>
 

diff --git a/content/docs/configuration/tools/index.mdx b/content/docs/configuration/tools/index.mdx
@@ -1,50 +1,90 @@
 ---
-title: Tools and Plugins
-icon: BookOpen
-description: Tools and Plugins setup instructions
+title: Tools
+icon: Wrench
+description: Configure built-in agent tools in LibreChat
 ---
 
-**Note:** A new approach has been devised to revamp the handling of tools and plugins from scratch. The plan is to prioritize implementation for Assistants initially, followed by creating a new agent system that seamlessly integrates with various endpoints such as Anthropic, Google, and others.
+LibreChat tools are selected from the **Agent Builder** and run when an agent decides they are useful. This section covers built-in agent tools such as image generation, search, weather, computation, and private index lookup.
 
-## Setup Instructions:
+<Callout type="info" title="Not the same as Web Search or MCP">
 
-### Azure AI Search
-- [Azure AI Search](/docs/configuration/tools/azure_ai_search)
+The search tools on this page are tools you add to a specific agent. LibreChat's built-in [Web Search](/docs/features/web_search) feature is configured separately, and custom third-party tools are usually added through [MCP](/docs/features/mcp) or [Actions](/docs/features/agents#actions).
 
-### Google Search
-- [Google Search](/docs/configuration/tools/google_search)
+</Callout>
 
-### OpenWeather
-- [OpenWeather](/docs/configuration/tools/openweather)
+## Quick Setup
 
-### Stable Diffusion
-- [Stable Diffusion](/docs/features/image_gen#3--stable-diffusion-local)
+<Steps>
+  <Step>
 
-### Flux
-- [Flux Image Generation](/docs/features/image_gen#4--flux)
+### Pick the Tool
 
-### Wolfram|Alpha
-- [Wolfram|Alpha](/docs/configuration/tools/wolfram)
+Choose a tool from the table below and collect any required API keys, service URLs, or index names.
 
-### DALL-E
-- You just need an OpenAI key, and it's made distinct from your main API key to make Chats but it can be the same one
+  </Step>
+  <Step>
 
-### Zapier
-- You need a Zapier account. Get your **[API key from here](https://nla.zapier.com/credentials/)** after you've made an account
-  - Create allowed actions - Follow step 3 in this **[Start Here guide](https://nla.zapier.com/start/)** from Zapier
-    - ⚠️ NOTE: zapier is known to be finicky with certain actions. I found that writing email drafts is probably the best use of it
+### Add Credentials
 
-### Browser/Scraper
-- This is not to be confused with 'browsing' on chat.openai.com (which is technically a plugin suite or multiple plugins)
-  - This plugin uses OpenAI embeddings so an OpenAI key is necessary, similar to DALL-E, and it's made distinct from your main API key to make Chats but it can be the same one
-  - This plugin will simply scrape html, and will not work with dynamic Javascript pages as that would require a more involved solution
-  - A better solution for 'browsing' is planned but can't guarantuee when
-  - This plugin is best used in combination with google so it doesn't hallucinate webpages to visit
+Add the required values to your `.env` file, or let users provide their own credentials from the LibreChat UI when the tool prompts for them.
 
-### SerpAPI
-- An alternative to Google search but not as performant in my opinion
-  - You can get an API key here: **[https://serpapi.com/dashboard](https://serpapi.com/dashboard)**
-  - For free tier, you are limited to 100 queries/month
-  - With google, you are limited to 100/day for free, which is a better deal, and any after may cost you a few pennies
+  </Step>
+  <Step>
 
+### Restart LibreChat
 
+Environment variable changes are loaded on restart.
+
+| Deployment | Command |
+|------------|---------|
+| Docker | `docker compose down && docker compose up -d` |
+| Local | Stop the server, then run `npm run backend` again |
+
+  </Step>
+  <Step>
+
+### Add the Tool to an Agent
+
+In LibreChat, select **Agents**, create or edit an agent, open the agent's **Tools** list, select the tool, and save the agent.
+
+  </Step>
+  <Step>
+
+### Test in Chat
+
+Start a chat with that agent and ask for something that requires the tool, such as a search, calculation, weather report, or image.
+
+  </Step>
+</Steps>
+
+## Current Built-In Tools
+
+| Tool | Use it for | Required configuration | Details |
+|------|------------|------------------------|---------|
+| OpenAI Image Tools | Generate and edit images with OpenAI image models | `IMAGE_GEN_OAI_API_KEY`; optional `IMAGE_GEN_OAI_MODEL` | [Image Generation](/docs/features/image_gen#1--openai-image-tools-recommended) |
+| Gemini Image Tools | Generate images and edit with image context using Gemini | `GEMINI_API_KEY`, `GOOGLE_KEY`, or `GOOGLE_SERVICE_KEY_FILE`; optional `GEMINI_IMAGE_MODEL` | [Gemini Image Generation](/docs/configuration/tools/gemini_image_gen) |
+| DALL-E-3 | Legacy OpenAI image generation | `DALLE3_API_KEY` or `DALLE_API_KEY` | [DALL-E](/docs/features/image_gen#3--dalle-legacy) |
+| Flux | Cloud image generation and fine-tuned image models | `FLUX_API_KEY`; optional `FLUX_API_BASE_URL` | [Flux](/docs/configuration/tools/flux) |
+| Stable Diffusion | Local or self-hosted image generation through Automatic1111 | `SD_WEBUI_URL` | [Stable Diffusion](/docs/configuration/tools/stable_diffusion) |
+| Google Search | Google Custom Search results for an agent | `GOOGLE_SEARCH_API_KEY` and `GOOGLE_CSE_ID` | [Google Search](/docs/configuration/tools/google_search) |
+| Tavily Search | Current web results optimized for agents | `TAVILY_API_KEY` | [Tavily Search](/docs/configuration/tools/tavily) |
+| Traversaal | AI search results with sources | `TRAVERSAAL_API_KEY` | [Traversaal](/docs/configuration/tools/traversaal) |
+| Azure AI Search | Search a private Azure AI Search index | `AZURE_AI_SEARCH_SERVICE_ENDPOINT`, `AZURE_AI_SEARCH_INDEX_NAME`, `AZURE_AI_SEARCH_API_KEY` | [Azure AI Search](/docs/configuration/tools/azure_ai_search) |
+| OpenWeather | Current, forecast, historical, and daily weather data | `OPENWEATHER_API_KEY` | [OpenWeather](/docs/configuration/tools/openweather) |
+| Wolfram\|Alpha | Math, computation, units, curated knowledge, and real-time data | `WOLFRAM_APP_ID` | [Wolfram\|Alpha](/docs/configuration/tools/wolfram) |
+| Calculator | Basic and complex calculations | None | [Calculator](/docs/configuration/tools/calculator) |
+
+## Tool Availability
+
+Tools are identified internally by their `pluginKey` from LibreChat's `api/app/clients/tools/manifest.json`.
+
+Use [`filteredTools`](/docs/configuration/librechat_yaml/object_structure/config#filteredtools) to hide tools, or [`includedTools`](/docs/configuration/librechat_yaml/object_structure/config#includedtools) to allow only specific tools:
+
+```yaml filename="librechat.yaml"
+includedTools:
+  - calculator
+  - image_gen_oai
+  - google
+```
+
+If a tool is not visible in the Agent Builder after restart, check the tool's environment variables, `includedTools`, `filteredTools`, and whether the agent's `tools` capability is enabled.
diff --git a/content/docs/configuration/tools/meta.json b/content/docs/configuration/tools/meta.json
@@ -8,9 +8,12 @@
     "stable_diffusion",
     "---Search---",
     "google_search",
+    "tavily",
+    "traversaal",
     "azure_ai_search",
     "---Other---",
     "openweather",
-    "wolfram"
+    "wolfram",
+    "calculator"
   ]
 }