🧭 refactor: web_search Description on When To Search vs Answer Directly (#13930)

* fix: stop agents from over-using the web_search tool

The web_search tool context injected into the agent system prompt was framed action-first ("execute immediately without preface") and never told the model when NOT to search. Models treat this as a default-on signal and search on nearly every turn, across all providers (Anthropic API, OpenRouter, etc.) since this instruction is provider-agnostic.

Reframe the instruction so the default is to answer from the model's own knowledge, gate searching behind a concrete trigger list, and explicitly reject the "a search might return relevant results" rationalization. Citation-format guidance is unchanged.

* refactor: make web_search guidance concise and neutral

Address maintainer feedback to keep the change minimal and generalized. Replace the verbose trigger list with a single neutral sentence: search when the user's request calls for it or when current/external information is required, and otherwise answer directly. Demote "execute immediately without preface" so it applies once a search is warranted rather than as the default, which was being read as "search on every turn."

packages/api/src/tools/toolkits/web.spec.ts

@@ -14,6 +14,13 @@ describe('web search context', () => {
     expect(context).not.toContain('{{iso_datetime}}');
   });
 
+  it('guides the model to answer directly when a search is not warranted', () => {
+    const context = buildWebSearchContext();
+
+    expect(context).toContain('respond directly without searching');
+    expect(context).toContain('current, real-time, or otherwise beyond your own knowledge');
+  });
+
   it('builds dynamic context from the supplied conversation anchor', () => {
     const context = buildWebSearchDynamicContext('2024-01-02T03:04:05.000Z');
     const secondContext = buildWebSearchDynamicContext('2024-01-02T03:04:05.000Z');

packages/api/src/tools/toolkits/web.ts

@@ -3,7 +3,7 @@ import { Tools, replaceSpecialVars } from 'librechat-data-provider';
 /** Builds the web search tool context with citation format instructions. */
 export function buildWebSearchContext(): string {
   return `# \`${Tools.web_search}\`:
-**Execute immediately without preface.** After search, provide a brief summary addressing the query directly, then structure your response with clear Markdown formatting (## headers, lists, tables). Cite sources properly, tailor tone to query type, and provide comprehensive details.
+Use this tool when the user's request calls for it, whether directly, indirectly, or implicitly, or when answering requires information that is current, real-time, or otherwise beyond your own knowledge; for questions you can answer reliably on your own, respond directly without searching. When searching, execute immediately without preface, then provide a brief summary addressing the query directly, then structure your response with clear Markdown formatting (## headers, lists, tables). Cite sources properly, tailor tone to query type, and provide comprehensive details.
 
 Use the conversation date/time from the dynamic runtime context when recency matters.