Add customize tools UI guide

docs/toolhive/guides-ui/customize-tools.mdx

@@ -0,0 +1,201 @@
+---
+title: Customize tools
+description:
+  Select which tools from an MCP server are available to your AI clients using
+  the ToolHive UI.
+---
+
+ToolHive lets you customize which tools from a running MCP server are available
+to your AI clients. You can enable or disable individual tools, and customize
+their names and descriptions. This gives you fine-grained control over the
+capabilities exposed by each server, helping you create focused tool sets and
+reduce complexity for your AI workflows.
+
+## Why customize tools?
+
+Customizing tools helps you:
+
+- **Reduce complexity**: Hide tools that aren't relevant to your workflow,
+  making it easier for AI clients to select the right tool
+- **Improve performance**: Fewer tools mean faster tool selection and reduced
+  token usage in AI interactions
+- **Enhance security**: Limit exposure to only the tools you need, reducing the
+  risk of unintended actions
+- **Create focused environments**: Tailor tool availability to specific tasks or
+  projects
+- **Clarify tool purpose**: Edit tool names and descriptions to make them more
+  understandable for your specific use case
+
+:::info[Registry match required]
+
+Tool customization is only available for MCP servers that match an entry in the
+registry. This includes:
+
+- Servers installed directly from the registry
+- Custom servers with a docker image or URL that matches a registry entry
+
+Custom servers that don't match any registry entry do not support this feature.
+
+:::
+
+## Access tool customization
+
+To customize tools for a running MCP server:
+
+1. Open the **MCP Servers** page.
+1. Find the server you want to customize and click the menu (︙) on its card.
+1. Select **Customize Tools** from the dropdown menu.
+
+The customize tools page displays all available tools from the MCP server, each
+with a toggle switch and description.
+
+:::note[Server must be running]
+
+The MCP server must be running to view and customize tools. If the server is
+stopped when you access the customize tools page, you'll see a message prompting
+you to start the server first.
+
+:::
+
+## Enable or disable tools
+
+On the customize tools page:
+
+1. Review the list of available tools and their descriptions.
+1. Use the toggle switches to enable or disable individual tools:
+   - **Green (enabled)**: The tool is available to AI clients
+   - **Gray (disabled)**: The tool is hidden from AI clients
+1. Click **Apply** to save your changes.
+
+The ToolHive proxy filters out disabled tools when AI clients connect to the
+server. Clients only see and can only call the tools you've enabled.
+
+:::warning[At least one tool required]
+
+You must keep at least one tool enabled. ToolHive prevents you from disabling
+all tools on a server, as this would make the server non-functional.
+
+:::
+
+## Edit tool names and descriptions
+
+You can customize the name and description of any tool to make it more suitable
+for your workflow. This is useful when the default tool name or description is
+unclear, or when you want to adapt the tool's presentation to your specific use
+case.
+
+To edit a tool:
+
+1. On the customize tools page, find the tool you want to edit.
+1. Click the **Edit** button next to the tool.
+1. In the dialog that opens:
+   - Edit the **Tool** field to change the tool's name.
+   - Edit the **Description** field to customize the tool's description.
+   - The original values are shown as helper text for reference.
+   - Leave either field empty to reset it to the original value.
+1. Click **Save** to apply your changes, or **Cancel** to discard them.
+
+Tools with custom names or descriptions are marked with a wrench icon to
+indicate they have custom overrides applied. The icon color indicates the
+status:
+
+- **Orange**: The tool has unsaved custom overrides
+- **Primary color**: The tool has saved custom overrides
+
+Your customizations are preserved even if you disable and re-enable the tool.
+
+:::tip[Unsaved custom overrides]
+
+If you customize a tool's name or description but haven't clicked **Apply** on
+the main page, a tooltip appears indicating "This tool has unsaved custom
+overrides". Click **Apply** to save both your tool selection changes and custom
+overrides.
+
+:::
+
+## How filtering works
+
+When you customize tools:
+
+1. You toggle tools on or off using the switches and optionally edit their names
+   and descriptions.
+1. After clicking **Apply**, your settings are saved to the server
+   configuration.
+1. The ToolHive proxy intercepts tool discovery requests from AI clients.
+1. Only enabled tools appear in the client's tool list, with your custom names
+   and descriptions if you've set them.
+1. If a client attempts to call a disabled tool directly, the proxy blocks the
+   request.
+
+This filtering happens transparently without requiring any changes to your AI
+client configuration. Your clients automatically see the updated tool list with
+customized names and descriptions the next time they connect.
+
+:::tip
+
+If you change tool settings while a client is connected, you may need to restart
+the client session to see the updated tool list. Some clients cache tool lists
+and don't automatically refresh.
+
+:::
+
+## Example workflows
+
+### Focus on specific GitHub operations
+
+If you're using the GitHub MCP server but only need pull request tools:
+
+1. Open **Customize Tools** for the GitHub server.
+1. Disable all tools except those related to pull requests (like
+   `create_pull_request`, `get_pull_request`, `list_pull_requests`).
+1. Your AI clients now see only pull request tools, making it easier to work
+   with GitHub PRs without distraction from issue, branch, or repository tools.
+
+### Create environment-specific tool sets
+
+If you're running the same MCP server in different groups for different
+environments:
+
+1. Copy the server to multiple groups (see
+   [Organize servers into groups](./group-management.mdx)).
+1. Customize tools in each group to match the environment's needs.
+1. For example, enable only read-only tools in a production group, while
+   allowing all tools in a development group.
+
+### Clarify technical tool names
+
+If an MCP server exposes tools with technical or unclear names:
+
+1. Open **Customize Tools** for the server.
+1. Click **Edit** on tools with unclear names.
+1. Change the tool name to something more descriptive (for example, rename
+   `list_commits_test` to `List Commits`).
+1. Update the description to clarify what the tool does in your context.
+1. Click **Save**, then **Apply**.
+1. Your AI clients now see clearer, more intuitive tool names and descriptions.
+
+## Reset to defaults
+
+To restore all tools to their default enabled state and remove custom overrides:
+
+**To reset an individual tool's name or description:**
+
+1. Click the **Edit** button next to the tool.
+1. Clear the **Tool** and **Description** fields (leave them empty).
+1. Click **Save**.
+1. Click **Apply** to save your changes.
+
+The tool name and description revert to their original values, and the wrench
+icon is removed.
+
+**To enable all tools:**
+
+1. Open the customize tools page for the server.
+1. Manually enable all tools using the toggle switches.
+1. Click **Apply** to save your changes.
+
+## Related information
+
+- [Run MCP servers](./run-mcp-servers.mdx)
+- [Organize servers into groups](./group-management.mdx)
+- [Client configuration](./client-configuration.mdx)

docs/toolhive/guides-ui/group-management.mdx

@@ -132,6 +132,18 @@ You cannot delete the `default` group.
 4. Use a different client or manually configure clients to access the
    "production" group when needed.
 
+### Create environment-specific tool sets
+
+If you're running the same MCP server in different groups for different
+environments:
+
+1. Copy the server to multiple groups (see
+   [Copy a server to a different group](#copy-a-server-to-a-different-group)).
+2. Customize tools in each group to match the environment's needs (see
+   [Customize tools](./customize-tools.mdx)).
+3. For example, enable only read-only tools in a production group, while
+   allowing all tools in a development group.
+
 ### Project-based organization
 
 1. Create groups for each project: "webapp-frontend", "webapp-backend", and

docs/toolhive/guides-ui/playground.mdx

@@ -77,6 +77,15 @@ To start using the playground:
 - The `toolhive mcp` server is included by default, providing management
   capabilities
 
+:::tip
+
+For more control over tool availability, use
+[Customize tools](./customize-tools.mdx) to permanently configure which tools
+are enabled for each registry server. The playground tool selection is temporary
+and only affects your testing session.
+
+:::
+
 4. **Start testing**: Begin chatting with your chosen AI model. The model will
    have access to all enabled MCP tools and can execute them based on your
    requests.

docs/toolhive/guides-ui/registry.mdx

@@ -86,6 +86,8 @@ After exploring the registry and finding servers you want to use:
 
 - **Install servers**: Click on servers from the registry to install and
   configure them for your environment
+- **Customize tools**: Selectively enable or disable tools from installed
+  registry servers to create focused tool sets
 - **Manage running servers**: Use the **MCP Servers** section to start, stop,
   and monitor your installed servers
 - **Create custom registries**: Set up your own private registry for

docs/toolhive/guides-ui/run-mcp-servers.mdx

@@ -487,6 +487,8 @@ automatically the next time you launch the application.
 
 - Connect ToolHive to AI clients like GitHub Copilot or Cursor using the
   [client configuration guide](./client-configuration.mdx).
+- Customize which tools are available from registry servers using the
+  [customize tools guide](./customize-tools.mdx).
 - Learn more about [secrets management](./secrets-management.mdx) to securely
   manage API tokens and other sensitive data.
 - Test your MCP servers using the [playground](./playground.mdx) to validate

sidebars.ts

@@ -62,6 +62,7 @@ const sidebars: SidebarsConfig = {
             'toolhive/guides-ui/group-management',
             'toolhive/guides-ui/secrets-management',
             'toolhive/guides-ui/network-isolation',
+            'toolhive/guides-ui/customize-tools',
           ],
         },
         'toolhive/guides-ui/client-configuration',