docs: add managing tools section and tool-router topic

documentation/docs/guides/environment-variables.md

@@ -144,14 +144,14 @@ export GOOSE_PLANNER_CONTEXT_LIMIT=1000000
 
 ## Tool Configuration
 
-These variables control how Goose handles [tool permissions](/docs/guides/tool-permissions) and their execution.
+These variables control how Goose handles [tool permissions](/docs/guides/managing-tools/tool-permissions) and their execution.
 
 | Variable | Purpose | Values | Default |
 |----------|---------|---------|---------|
 | `GOOSE_MODE` | Controls how Goose handles tool execution | "auto", "approve", "chat", "smart_approve" | "smart_approve" |
 | `GOOSE_TOOLSHIM` | Enables/disables tool call interpretation | "1", "true" (case insensitive) to enable | false |
 | `GOOSE_TOOLSHIM_OLLAMA_MODEL` | Specifies the model for [tool call interpretation](/docs/guides/experimental-features/#ollama-tool-shim) | Model name (e.g. llama3.2, qwen2.5) | System default |
-| `GOOSE_CLI_MIN_PRIORITY` | Controls verbosity of [tool output](/docs/guides/adjust-tool-output) | Float between 0.0 and 1.0 | 0.0 |
+| `GOOSE_CLI_MIN_PRIORITY` | Controls verbosity of [tool output](/docs/guides/managing-tools/adjust-tool-output) | Float between 0.0 and 1.0 | 0.0 |
 | `GOOSE_CLI_TOOL_PARAMS_TRUNCATION_MAX_LENGTH` | Maximum length for tool parameter values before truncation in CLI output (not in debug mode) | Integer | 40 |
 
 **Examples**
@@ -196,6 +196,36 @@ export GOOSE_EDITOR_HOST="http://localhost:8000/v1"
 export GOOSE_EDITOR_MODEL="your-model"
 ```
 
+
+## Tool Selection Strategy
+
+These variables configure the [tool selection strategy](/docs/guides/managing-tools/tool-router).
+
+| Variable | Purpose | Values | Default |
+|----------|---------|---------|--------|
+| `GOOSE_ROUTER_TOOL_SELECTION_STRATEGY` | The tool selection strategy to use | "default", "vector", "llm" | "default" |
+| `GOOSE_EMBEDDING_MODEL_PROVIDER` | The provider to use for generating embeddings for the "vector" strategy | [See available providers](/docs/getting-started/providers#available-providers) (must support embeddings) | "openai" |
+| `GOOSE_EMBEDDING_MODEL` | The model to use for generating embeddings for the "vector" strategy | Model name (provider-specific) | "text-embedding-3-small" |
+
+**Examples**
+
+```bash
+# Use vector-based tool selection with custom settings
+export GOOSE_ROUTER_TOOL_SELECTION_STRATEGY=vector
+export GOOSE_EMBEDDING_MODEL_PROVIDER=ollama
+export GOOSE_EMBEDDING_MODEL=nomic-embed-text
+
+# Or use LLM-based selection
+export GOOSE_ROUTER_TOOL_SELECTION_STRATEGY=llm
+```
+
+**Embedding Provider Support**
+
+The default embedding provider is OpenAI. If using a different provider:
+- Ensure the provider supports embeddings
+- Specify an appropriate embedding model for that provider
+- Ensure the provider is properly configured with necessary credentials
+
 ## Security Configuration
 
 These variables control security related features.

documentation/docs/guides/managing-tools/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Managing Tools",
+  "position": 2,
+  "link": {
+    "type": "doc",
+    "id": "guides/managing-tools/index"
+  }
+}

documentation/docs/guides/adjust-tool-output.md → documentation/docs/guides/managing-tools/adjust-tool-output.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 11
+sidebar_position: 2
 title: Adjusting Tool Output Verbosity
 sidebar_label: Adjust Tool Output
 ---

documentation/docs/guides/managing-tools/index.md

@@ -0,0 +1,60 @@
+---
+title: Managing Tools
+hide_title: true
+description: Control and configure the tools and extensions that power your Goose workflows
+---
+
+import Card from '@site/src/components/Card';
+import styles from '@site/src/components/Card/styles.module.css';
+
+<h1 className={styles.pageTitle}>Managing Tools</h1>
+<p className={styles.pageDescription}>
+  Tools are specific functions within <a href="/docs/getting-started/using-extensions">extensions</a> that give Goose its capabilities. Learn to control and customize how these tools work for you.
+</p>
+
+<div className={styles.categorySection}>
+  <h2 className={styles.categoryTitle}>📚 Documentation & Guides</h2>
+  <div className={styles.cardGrid}>
+    <Card 
+      title="Tool Permissions"
+      description="Configure fine-grained permissions to control which tools Goose can use and when, ensuring secure and controlled automation."
+      link="/docs/guides/managing-tools/tool-permissions"
+    />
+    <Card 
+      title="Tool Selection Strategy"
+      description="Optimize tool selection with dynamic routing that loads only the tools you need, reducing context overhead and improving performance."
+      link="/docs/guides/managing-tools/tool-router"
+    />
+    <Card 
+      title="Adjust Tool Output"
+      description="Customize how tool interactions are displayed, from detailed verbose output to clean concise summaries."
+      link="/docs/guides/managing-tools/adjust-tool-output"
+    />
+    <Card 
+      title="Ollama Tool Shim"
+      description="Enable tool calling for models that don't natively support it using an experimental local interpreter model setup."
+      link="/docs/guides/experimental-features#ollama-tool-shim"
+    />
+  </div>
+</div>
+
+<div className={styles.categorySection}>
+  <h2 className={styles.categoryTitle}>📝 Featured Blog Posts</h2>
+  <div className={styles.cardGrid}>
+    <Card
+      title="Agentic AI and the MCP Ecosystem"
+      description="A 101 introduction to AI agents, tool calling, and how tools work with LLMs to enable powerful automation."
+      link="/blog/2025/02/17/agentic-ai-mcp"
+    />
+    <Card
+      title="A Visual Guide To MCP Ecosystem"
+      description="Visual breakdown of MCP: How your AI agent, tools, and models work together, explained with diagrams and analogies."
+      link="/blog/2025/04/10/visual-guide-mcp"
+    />
+    <Card
+      title="Finetuning Toolshim Models for Tool Calling"
+      description="Technical deep-dive into the challenges of tool calling with open-source models and the research behind toolshim solutions."
+      link="/blog/2025/04/11/finetuning-toolshim"
+    />
+  </div>
+</div>

documentation/docs/guides/tool-permissions.md → documentation/docs/guides/managing-tools/tool-permissions.md

@@ -1,6 +1,6 @@
 ---
 title: Managing Tool Permissions
-sidebar_position: 4
+sidebar_position: 1
 sidebar_label: Tool Permissions
 ---
 

documentation/docs/guides/managing-tools/tool-router.md

@@ -0,0 +1,162 @@
+---
+sidebar_position: 3
+title: Tool Selection Strategy
+sidebar_label: Tool Selection Strategy
+description: Configure smart tool selection to load only relevant tools, improving performance with multiple extensions
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+:::info Preview Feature
+The Tool Selection Strategy is currently in preview. The Vector selection strategy is currently limited to Claude models served on Databricks.
+:::
+
+When you enable an [extension](/docs/getting-started/using-extensions), you gain access to all of its tools. For example, the Google Drive extension provides tools for reading documents, updating permissions, managing comments, and more. By default, Goose loads all tools into context when interacting with the LLM.
+
+Enabling multiple extensions gives you access to a wider range of tools, but loading a lot of tools into context can be inefficient and confusing for the LLM. It's like having every tool in your workshop spread out on your bench when you only need one or two. 
+
+Choosing an intelligent tool selection strategy helps avoid this problem. Instead of loading all tools for every interaction, it loads only the tools needed for your current task. Both vector and LLM-based strategies ensure that only the functionality you need is loaded into context, so you can keep more of your favorite extensions enabled. These strategies provide:
+
+- Reduced token consumption
+- Improved LLM performance
+- Better context management
+- More accurate and efficient tool selection
+
+## Tool Selection Strategies
+
+| Strategy | Speed | Best For | Example Query |
+|----------|-------|----------|---------------|
+| **Default** | Fastest | Few extensions, simple setups | Any query (loads all tools) |
+| **Vector** | Fast | Keyword-based matching | "read pdf file" |
+| **LLM-based** | Slower | Complex, ambiguous queries | "analyze document contents" |
+
+### Default Strategy
+The default strategy loads all tools from enabled extensions into context, which works well if you only have a few extensions enabled. When you have more than a few extensions enabled, you should use the vector or LLM-based strategy for intelligent tool selection.
+
+**Best for:**
+- Simple setups with few extensions
+- When you want all tools available at all times
+- Maximum tool availability without selection logic
+
+### Vector Strategy
+The vector strategy uses mathematical similarity between embeddings to find relevant tools, providing efficient matching based on vector similarity between your query and available tools.
+
+**Best for:**
+- Situations where fast response times are critical
+- Queries with keywords that match tool names or descriptions
+
+**Example:**
+- Prompt: "read pdf file"
+- Result: Quickly matches with PDF-related tools based on keyword similarity
+
+:::info Embedding Model
+The default embedding model is `text-embedding-3-small`. You can change it using [environment variables](/docs/guides/environment-variables#tool-selection-strategy).
+:::
+
+### LLM-based Strategy
+The LLM-based strategy leverages natural language understanding to analyze tools and queries semantically, making selections based on the full meaning of your request.
+
+**Best for:**
+- Complex or ambiguous queries that require understanding context
+- Cases where exact keyword matches might miss relevant tools
+- Situations where nuanced tool selection is important
+
+**Example:**
+- Prompt: "help me analyze the contents of my document"
+- Result: Understands context and might suggest both PDF readers and content analysis tools
+
+## Configuration
+
+<Tabs groupId="interface">
+  <TabItem value="ui" label="Goose Desktop" default>
+    1. Click the gear icon ⚙️ on the top toolbar
+    2. Click `Advanced settings`
+    3. Under `Tool Selection Strategy`, select your preferred strategy:
+       - `Default`
+       - `Vector`
+       - `LLM-based`
+  </TabItem>
+  <TabItem value="cli" label="Goose CLI">
+    1. Run the `configuration` command:
+    ```sh
+    goose configure
+    ```
+
+    2. Select `Goose Settings`:
+    ```sh
+    ┌   goose-configure
+    │
+    ◆  What would you like to configure?
+    │  ○ Configure Providers
+    │  ○ Add Extension
+    │  ○ Toggle Extensions
+    │  ○ Remove Extension
+    // highlight-start
+    │  ● Goose Settings (Set the Goose Mode, Tool Output, Tool Permissions, Experiment, Goose recipe github repo and more)
+    // highlight-end
+    └ 
+    ```
+
+    3. Select `Router Tool Selection Strategy`:
+    ```sh
+    ┌   goose-configure
+    │
+    ◇  What would you like to configure?
+    │  Goose Settings
+    │
+    ◆  What setting would you like to configure?
+    │  ○ Goose Mode 
+    // highlight-start
+    │  ● Router Tool Selection Strategy (Configure the strategy for selecting tools to use)
+    // highlight-end
+    │  ○ Tool Permission 
+    │  ○ Tool Output 
+    │  ○ Toggle Experiment 
+    │  ○ Goose recipe github repo 
+    └ 
+    ```
+
+    4. Select your preferred strategy:
+    ```sh
+   ┌   goose-configure 
+   │
+   ◇  What would you like to configure?
+   │  Goose Settings 
+   │
+   ◇  What setting would you like to configure?
+   │  Router Tool Selection Strategy 
+   │
+    // highlight-start
+   ◆  Which router strategy would you like to use?
+   │  ● Vector Strategy (Use vector-based similarity to select tools)
+   │  ○ Default Strategy 
+    // highlight-end
+   └  
+    ```
+
+       :::info
+       Currently, the LLM-based strategy can't be configured using the CLI.
+       :::
+
+       This example output shows the `Vector Strategy` was selected:
+
+    ```
+    ┌   goose-configure
+    │
+    ◇  What would you like to configure?
+    │  Goose Settings
+    │
+    ◇  What setting would you like to configure?
+    │  Router Tool Selection Strategy
+    │
+    ◇  Which router strategy would you like to use?
+    │  Vector Strategy
+    │
+    └  Set to Vector Strategy - using vector-based similarity for tool selection
+    ```
+
+    Goose CLI display a message indicating when the vector or LLM-based strategy is currently being used.
+
+  </TabItem>
+</Tabs>

documentation/docs/guides/tips.md

@@ -24,7 +24,7 @@ Your experience with Goose is shaped by your [choice of LLM](/blog/2025/03/31/go
 LLMs have context windows, which are limits on how much conversation history they can retain. Once exceeded, they may forget earlier parts of the conversation. Monitor your token usage and [start new sessions](/docs/guides/managing-goose-sessions) as needed.
 
 ### Turn off unnecessary extensions or tool
-Turning on too many extensions can degrade performance. Enable only essential [extensions and tools](/docs/guides/tool-permissions) to improve tool selection accuracy, save context window space, and stay within provider tool limits.
+Turning on too many extensions can degrade performance. Enable only essential [extensions and tools](/docs/guides/managing-tools/tool-permissions) to improve tool selection accuracy, save context window space, and stay within provider tool limits.
 
 ### Teach Goose your preferences
 Help Goose remember how you like to work by using [`.goosehints`](/docs/guides/using-goosehints/) for permanent project preferences and the [Memory extension](/docs/mcp/memory-mcp) for things you want Goose to dynamically recall later. Both can help save valuable context window space while keeping your preferences available.