Add customize tools UI guide

[samuv]

Description

Added and enhanced documentation for the customize tools feature in the ToolHive UI. This page (docs/toolhive/guides-ui/customize-tools.mdx) explains how users can selectively enable or disable tools from MCP servers, and customize tool names and descriptions.

Key content covered:

• Benefits of customizing tools (reduced complexity, improved performance, enhanced security, clarifying tool purpose)
• Registry match requirement: Feature only works for servers that match a registry entry (by docker image or URL)
• How to access the customize tools page from the server dropdown menu
• Step-by-step instructions for enabling/disabling tools with toggle switches
• NEW: How to edit tool names and descriptions for better clarity
• NEW: Wrench icon indicator showing customization status:
  • Orange: Unsaved custom overrides
  • Primary color: Saved custom overrides
• Requirement to click Apply to save changes
• Behavior when server is not running (dedicated message prompting user to start server)
• How the proxy filters tools and applies custom overrides for AI clients
• Example workflows for common use cases, including clarifying technical tool names
• At least one tool must remain enabled
• How to reset tools to their default state

Cross-references added:

• Added link from run-mcp-servers.mdx "Next steps" section (critical discovery path)
• Added mention in registry.mdx "Next steps" section
• Added tip in playground.mdx explaining difference between temporary playground selection and permanent customization
• Added example workflow in group-management.mdx demonstrating environment-specific tool sets

The page is added to the sidebar under "Guides: ToolHive UI" → "Run MCP servers" section.

Related issues/PRs

• Implements feature from feat(customize-tools): add tool overide to customize table toolhive-studio#1230

Screenshots

N/A - Documentation only

Merge checklist

Content

• New pages include a frontmatter section with title and description at a minimum
• Sidebar navigation (sidebars.ts) updated for added, deleted, reordered, or renamed files
• Cross-references added to related pages for better discoverability

Reviews

• Content has been reviewed for technical accuracy
• Content has been reviewed for spelling, grammar, and style
• Addressed Claude bot review feedback

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
docs-website	Ready	Preview	Comment	Nov 6, 2025 3:42pm

[Copilot]

Pull Request Overview

This PR adds comprehensive documentation for the customize tools feature in ToolHive UI, which allows users to selectively enable or disable tools from MCP servers installed from the registry.

Key changes:

• New documentation page explaining tool customization functionality with step-by-step instructions
• Sidebar navigation updated to include the new customize tools guide
• Coverage of benefits, workflows, and technical details of the proxy filtering mechanism

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
sidebars.ts	Added customize-tools page to the guides-ui navigation structure
docs/toolhive/guides-ui/customize-tools.mdx	New comprehensive guide covering tool customization feature with examples and workflows

[danbarr]

@claude please review this new how-to guide for clarity and consistency with the project style guide. Also suggest where some cross-references from existing pages would make sense.

[claude]

Claude finished @danbarr's task —— View job

---

Review complete

I've reviewed the new customize tools documentation for clarity and consistency with the project style guide. Overall, this is well-written documentation that follows the style guide closely. Below are my findings organized by category.

---

Style and clarity feedback

Strengths

• Clear, conversational tone that matches the project style guide
• Good use of admonitions (info, note, warning, tip) to highlight important information
• Effective organization with logical flow from "why" to "how" to "examples"
• Strong use of active voice throughout
• Proper use of the Oxford comma
• Example workflows are practical and helpful

Suggestions for improvement

1. Minor capitalization inconsistency (line 38)
The term "menu" should not be in parentheses with the symbol. Based on other pages in the codebase, consider:

Find the server you want to customize and click the menu (︙) on its card.


Find the server you want to customize and click the **menu (︙)** on its card.

Or better yet, match the pattern from run-mcp-servers.mdx:202:

Click the **menu (︙)** on the server card and select **Customize Tools** from the dropdown menu.

2. Redundant phrase (line 39)
"dropdown menu" after "Select Customize Tools from the dropdown menu" is redundant since line 38 already establishes it's a menu.

3. Consider adding bold formatting for UI elements (lines 58-59)
For consistency with the style guide ("Bold: use when referring to UI elements"), consider:

- **Green (enabled)**: The tool is available to AI clients
- **Gray (disabled)**: The tool is hidden from AI clients


- Green (enabled): The tool is available to AI clients
- Gray (disabled): The tool is hidden from AI clients

Actually, looking at this more carefully, the colors themselves aren't UI elements—they're visual states. The current formatting is acceptable, but you could also write it as:

- Enabled (green): The tool is available to AI clients
- Disabled (gray): The tool is hidden from AI clients

4. "Reset to defaults" section (lines 119-128)
This section feels slightly apologetic ("There is no automatic 'reset all' button, but..."). Consider a more direct approach:

## Reset to defaults

To restore all tools to their default enabled state:

1. Open the customize tools page for the server.
1. Enable all tools using the toggle switches.
1. Click **Apply** to save your changes.

5. Inconsistent reference style (line 113)
The cross-reference uses present tense, but the style guide recommends using sentence case that matches the target title:

1. Copy the server to multiple groups (see [Organize servers into groups](./group-management.mdx)).


1. Copy the server to multiple groups (see [Organize servers into groups](./group-management.mdx)).

This is actually correct as-is!

---

Cross-reference suggestions

Pages that should link TO customize-tools.mdx

1. run-mcp-servers.mdx (HIGH PRIORITY)
Add a cross-reference in the "Manage MCP servers" section after line 465 or as a new bullet point:

- **Customize tools**: Click the menu (︙) on the server card and select **Customize Tools** to enable or disable individual tools from registry servers. See [Customize tools](./customize-tools.mdx) for details.

Also consider adding to the "Next steps" section (after line 492):

- Customize which tools are available from registry servers using the [customize tools guide](./customize-tools.mdx).

2. registry.mdx (MEDIUM PRIORITY)
Add a mention in the "View server details" section or "Next steps" section (after line 85):

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

3. playground.mdx (MEDIUM PRIORITY)
In the "Using the playground" section after line 72, add context about the relationship:

- Enable or disable specific tools from each server
- Search and filter tools by name or functionality
- 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. group-management.mdx (MEDIUM PRIORITY)
In the example workflows section, the "Create environment-specific tool sets" workflow mentions customizing tools. Consider enhancing line 115:

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 (see [Customize tools](./customize-tools.mdx)).
1. For example, enable only read-only tools in a production group, while allowing all tools in a development group.

5. client-configuration.mdx (LOW PRIORITY)
Could add a brief mention in the "Related information" section, though this is lower priority since the connection is less direct.

---

Technical accuracy

The documentation accurately describes the feature behavior:

• Correctly notes that tool customization is only for registry servers
• Accurately explains the proxy filtering mechanism
• Properly warns about the one-tool minimum requirement
• Correctly describes the Apply button requirement
• Appropriately mentions client caching behavior

---

Additional observations

1. Missing screenshot? The PR description mentions "Screenshots: N/A - Documentation only", but this type of UI-focused how-to guide would benefit greatly from at least one screenshot showing the customize tools interface with toggle switches. Consider adding one in a future iteration.

2. Consistency with existing patterns: The page follows the same structural patterns as other guides (Why → How → Examples → Related), which is excellent for user navigation.

3. SEO and discoverability: The front matter description is clear and includes good keywords. The title "Customize tools" is concise and matches user mental models.

---

Summary

This is high-quality documentation that requires only minor adjustments. The main action items are:

1. Critical: Add cross-references from run-mcp-servers.mdx (the most natural place users will discover this feature)
2. Recommended: Add cross-references from registry.mdx and playground.mdx
3. Optional: Minor style tweaks for the "Reset to defaults" section and UI element formatting
4. Future enhancement: Consider adding a screenshot of the customize tools interface

The content is clear, accurate, and well-organized. Great work!

---