tkmind/tkmind_go
1
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity

docs: add managing tools section and tool-router topic (#3310)

Browse Source 
Co-authored-by: Rizel Scarlett <rizel@squareup.com>
This commit is contained in:
dianed-square
2025-07-09 07:47:53 -07:00
committed by GitHub
parent c8504b2a41
commit 2f36bac577
9 changed files with 281 additions and 95 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentation/docs/guides/managing-tools/_category_.json
+8
View File
@@ -0,0 +1,8 @@
{
"label": "Managing Tools",
"position": 2,
"link": {
"type": "doc",
"id": "guides/managing-tools/index"
}
}
documentation/docs/guides/managing-tools/adjust-tool-output.md
+85
View File
@@ -0,0 +1,85 @@
---
sidebar_position: 2
title: Adjusting Tool Output Verbosity
sidebar_label: Adjust Tool Output
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
<Tabs groupId="interface">
<TabItem value="ui" label="Goose Desktop" default>
Response Styles customize how tool interactions are displayed in the Goose Desktop chat window.
To change this setting:
1. Click the menu icon in the top right corner.
2. Select `Advanced Settings` from the menu.
3. Under `Response Styles`, select either `Detailed` or `Concise`.
- **Concise** (Default)
- Tool calls are collapsed by default
- Shows only which tool Goose used
- Best for users focusing on results rather than technical details
- **Detailed**
- Tool calls are expanded by default
- Shows the details of tool calls and their responses
- Best for debugging or learning how Goose works
This setting only affects the default state of tool calls in the conversation. You can always manually expand or collapse any tool call regardless of your chosen style.
</TabItem>
<TabItem value="cli" label="Goose CLI">
When working with the Goose CLI, you can control the verbosity of tool output.
To adjust the tool output, run:
```sh
goose configure
```
Then choose `Adjust Tool Output`
```sh
┌ goose-configure
│
◆ What would you like to configure?
│ ○ Configure Providers
│ ○ Add Extension
│ ○ Toggle Extensions
│ ○ Remove Extension
// highlight-next-line
│ ● Adjust Tool Output (Show more or less tool output)
└
```
Next, choose one of the available modes:
```sh
┌ goose-configure
│
◇ What would you like to configure?
│ Adjust Tool Output
│
// highlight-start
◆ Which tool output would you like to show?
│ ○ High Importance
│ ○ Medium Importance
│ ○ All
// highlight-end
└
```
- **High Importance**
- Shows only the most important tool outputs
- Most minimal output level
- **Medium Importance**
- Shows medium and high importance outputs
- Example: Results of file-write operations
- **All**
- Shows all tool outputs
- Example: Shell command outputs
- Most verbose level
</TabItem>
</Tabs>
documentation/docs/guides/managing-tools/index.md
+60
View File
@@ -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/managing-tools/tool-permissions.md
+173
View File
@@ -0,0 +1,173 @@
---
title: Managing Tool Permissions
sidebar_position: 1
sidebar_label: Tool Permissions
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
Tool permissions provide fine-grained control over how Goose uses different tools within extensions. This guide will help you understand and configure these permissions effectively.
## Understanding Tools and Extensions
Before diving into permissions, let's clarify the key components:
- **Extensions** are packages that add functionality to Goose (like Developer, Google Drive, etc.)
- **Tools** are specific functions within each extension that Goose can use
For example, the Developer extension includes multiple tools like:
- Text editor tool for file editing
- Shell tool for running commands
- Screen capture tool for taking screenshots
:::warning Performance Optimization
Goose performs best with fewer than 25 total tools enabled across all extensions. Consider enabling only the extensions you need for your current task.
:::
## Permission Levels
Each tool can be set to one of three permission levels:
| Permission Level | Description | Best For | Examples |
|-----------------|-------------|-----------|----------|
| **Always Allow** | Tool runs without requiring approval | Safe, read-only operations | • File reading<br></br>• Directory listing<br></br>• Information retrieval |
| **Ask Before** | Requires confirmation | State-changing operations | • File writing/editing<br></br>• System commands<br></br>• Resource creation |
| **Never Allow** | Tool cannot be used | Sensitive operations | • Credential access<br></br>• System-critical files<br></br>• Resource deletion |
:::info
Tool permissions work alongside [Goose Permission Modes](/docs/guides/goose-permissions). The mode sets default behavior, while tool permissions let you override specific tools.
:::
## Configuring Tool Permissions
<Tabs groupId="interface">
<TabItem value="ui" label="Goose Desktop" default>
You can configure tool permissions through either Manual or Smart Approval modes:
<Tabs>
<TabItem value="manual" label="Manual Approval" default>
1. Click `...` in the upper right corner
2. Click `Advanced Settings`
3. Under `Mode Selection`, choose `Manual Approval`
4. Click on an extension name
5. Use the dropdown next to each tool to set its permission level
</TabItem>
<TabItem value="smart" label="Smart Approval">
:::tip
In Smart Approval mode, Goose will automatically detect and allow read-only operations while requiring approval for state-changing actions.
:::
1. Click `...` in the upper right corner
2. Click `Advanced Settings`
3. Under `Mode Selection`, choose `Smart Approval`
4. Click on an extension name
5. Use the dropdown next to each tool to set its permission level
</TabItem>
</Tabs>
</TabItem>
<TabItem value="cli" label="Goose CLI">
1. Run the configure command:
```sh
goose configure
```
2. Select `Goose Settings` from the menu
```sh
┌ goose-configure
│
◆ What would you like to configure?
| ○ Configure Providers
| ○ Add Extension
| ○ Toggle Extensions
| ○ Remove Extension
// highlight-start
| ● Goose Settings
// highlight-end
└
```
3. Choose `Tool Permission`
```sh
┌ goose-configure
│
◇ What would you like to configure?
│ Goose Settings
│
◆ What setting would you like to configure?
│ ○ Goose Mode
// highlight-start
│ ● Tool Permission
// highlight-end
| ○ Tool Output
└
```
4. Select an extension and configure permissions for its tools:
```sh
┌ goose-configure
│
◇ What setting would you like to configure?
│ Tool Permission
│
◇ Choose an extension to configure tools
│ developer
│
◇ Choose a tool to update permission
│ developer__image_processor
│
◆ Set permission level for tool developer__image_processor, current permission level: Not Set
│ ○ Always Allow
// highlight-start
│ ● Ask Before (Prompt before executing this tool)
// highlight-end
│ ○ Never Allow
└
```
</TabItem>
</Tabs>
## Benefits of Permission Management
:::tip
Review and update your tool permissions as your tasks change. You can modify permissions at any time during a session.
:::
There are several reasons to configure tool permissions:
1. **Performance Optimization**
- Keep total enabled tools under 25 for best performance
- Disable tools you don't need for your current task
- Reduce context window usage and improve response quality
- Prevent tool decision paralysis
2. **Security Control**
- Restrict access to sensitive operations
- Prevent accidental file modifications
- Control system resource usage
3. **Task Focus**
- Enable only tools needed for current task
- Help Goose make better tool choices
- Reduce noise in responses
## Example Permission Configuration
### Task-Based Configuration
Configure permissions based on your current task:
```
Development Task:
✓ File reading → Always Allow
✓ Code editing → Ask Before
✓ Test running → Always Allow
✗ System commands → Ask Before
Documentation Task:
✓ File reading → Always Allow
✓ Markdown editing → Always Allow
✗ Code editing → Never Allow
✗ System commands → Never Allow
```
documentation/docs/guides/managing-tools/tool-router.md
+162
View File
@@ -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>