feat(meta-tools): guide @mux to optimize minimal-first, expand on demand

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>

Author: its-mash

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

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 {