From 4fcabcafae18967cabe6ecfbc4be3d0954cb045f Mon Sep 17 00:00:00 2001
From: Mohammod Al Amin Ashik <maa.ashik00@gmail.com>
Date: Mon, 15 Jun 2026 18:17:54 +0800
Subject: [PATCH] feat(meta-tools): guide @mux to optimize minimal-first,
 expand on demand
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Composing a toolset was slow because the model would dump the whole
catalog (mcpmux_list_all_tools), reason over all of it, then build one
large FeatureSet upfront. Steer it toward a lean, incremental strategy
in the guidance the model actually reads:

- Server instructions: add an explicit "start minimal and expand on
  demand" directive — search for just the tools the task needs, compose
  a small FeatureSet, then grow it later (manage_feature_set update +
  add) only as new needs arise. Don't over-curate; re-optimizing is
  cheap.
- mcpmux_list_all_tools description: point to mcpmux_search_tools for the
  common case; call out the full dump as the most token-heavy read.
- mcpmux_manage_feature_set description: prefer a small initial set
  expanded later over adding every candidate tool upfront.

Guidance-only; no behavior change to the tools themselves.

Signed-off-by: Mohammod Al Amin Ashik <maa.ashik00@gmail.com>
---
 crates/mcpmux-gateway/src/mcp/handler.rs              | 11 ++++++++++-
 .../mcpmux-gateway/src/services/meta_tools/tools.rs   | 11 +++++++----
 2 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/crates/mcpmux-gateway/src/mcp/handler.rs b/crates/mcpmux-gateway/src/mcp/handler.rs
index 2a50d315..1160cafc 100644
--- a/crates/mcpmux-gateway/src/mcp/handler.rs
+++ b/crates/mcpmux-gateway/src/mcp/handler.rs
@@ -368,7 +368,16 @@ impl ServerHandler for McpMuxGatewayHandler {
              list_feature_sets) are safe to call freely once the user has opted \
              in; writes (manage_feature_set, bind_current_workspace) prompt the \
              user for approval. Most operations accept an optional `space_id` \
-             (from mcpmux_list_spaces) to target a specific Space."
+             (from mcpmux_list_spaces) to target a specific Space.\n\n\
+             When optimizing, start minimal and expand on demand. Use \
+             `mcpmux_search_tools` to find just the tools the current task needs \
+             and compose a small FeatureSet, then grow it later \
+             (`mcpmux_manage_feature_set` action 'update' with `add`) only as new \
+             needs arise. Prefer this over dumping the whole catalog with \
+             `mcpmux_list_all_tools` and adding everything upfront — a lean set is \
+             faster to assemble, cheaper in tokens, and keeps the agent's tool \
+             list focused. Don't over-curate: a few clearly-needed tools now beats \
+             an exhaustive set, and re-optimizing is cheap."
                 .to_string(),
         );
         info
diff --git a/crates/mcpmux-gateway/src/services/meta_tools/tools.rs b/crates/mcpmux-gateway/src/services/meta_tools/tools.rs
index 0675c32f..c640dc49 100644
--- a/crates/mcpmux-gateway/src/services/meta_tools/tools.rs
+++ b/crates/mcpmux-gateway/src/services/meta_tools/tools.rs
@@ -116,9 +116,10 @@ impl MetaTool for ListAllToolsTool {
     fn description(&self) -> &'static str {
         "List every tool installed in a Space (default: the caller's resolved \
          Space; pass `space_id` to target another), without the current \
-         FeatureSet filter applied. Use this to see what could be exposed \
-         before composing a custom FeatureSet. Returns an array of \
-         {server_id, qualified_name, description, available}."
+         FeatureSet filter applied. Prefer `mcpmux_search_tools` for the common \
+         case — only fall back to this full catalog dump when you genuinely need \
+         to enumerate everything, since it's the most token-heavy read. Returns \
+         an array of {server_id, qualified_name, description, available}."
     }
 
     fn input_schema(&self) -> Value {
@@ -716,7 +717,9 @@ impl MetaTool for ManageFeatureSetTool {
          (needs `feature_set_id`). Tool names are the qualified names from \
          `mcpmux_list_all_tools`/`mcpmux_search_tools`. Built-in sets can't be \
          modified. Requires user approval. Route a workspace through a FeatureSet \
-         with `mcpmux_bind_current_workspace`."
+         with `mcpmux_bind_current_workspace`. Prefer composing a small initial \
+         set and expanding it later (action 'update' with `add`) as the task \
+         needs more, rather than adding every candidate tool upfront."
     }
 
     fn input_schema(&self) -> Value {