feat(meta-tools): add mcpmux_search_tools for keyword tool discovery

`mcpmux_list_all_tools` returns the entire tool catalog for the resolved Space
in one payload — expensive in token terms once a Space has many servers. Add a
read-only `mcpmux_search_tools` so an agent that knows roughly what it wants can
find tools by keyword instead of dumping everything.

- Case-insensitive substring match over qualified_name, server_id, and
  description, scoped to the caller''s resolved Space.
- `limit` (default 25, hard max 100); results sorted by qualified_name before
  truncation; response carries match_count / returned / truncated so the caller
  knows when to narrow the query.
- Registered as a read tool (no approval) alongside list_all_tools; added to the
  Tool Optimization built-in descriptor so the desktop shelf lists it.

Integration tests cover name/server/description matching, empty results,
missing-query rejection, and limit/truncation.

Signed-off-by: Mohammod Al Amin Ashik <maa.ashik00@gmail.com>

Author: its-mash

crates/mcpmux-core/src/domain/builtin.rs

@@ -61,6 +61,11 @@ pub fn builtin_servers() -> Vec<BuiltinServerDescriptor> {
                 description: "Browse every tool available in the resolved Space, unfiltered.",
                 write: false,
             },
+            BuiltinToolDescriptor {
+                name: "mcpmux_search_tools",
+                description: "Find tools by keyword without pulling the whole catalog.",
+                write: false,
+            },
             BuiltinToolDescriptor {
                 name: "mcpmux_list_feature_sets",
                 description: "See the feature sets defined in the Space.",

crates/mcpmux-gateway/src/services/meta_tools/mod.rs

@@ -78,10 +78,11 @@ pub fn build_default_registry(
     let mut registry = MetaToolRegistry::new(ctx);
     // Reads — no approval needed.
     registry.register(Box::new(tools::ListAllToolsTool));
+    registry.register(Box::new(tools::SearchToolsTool));
     registry.register(Box::new(tools::ListFeatureSetsTool));
     // Both `describe_resolution` and `describe_workspace` were removed by
-    // user request — the read surface is just the two list_* tools above,
-    // which an LLM can stitch into the same picture without an extra hop.
+    // user request — the read surface is the list_* tools above plus
+    // `search_tools`, which an LLM can stitch into the same picture.
     // Writes — gated by ApprovalBroker.
     registry.register(Box::new(tools::ManageFeatureSetTool));
     registry.register(Box::new(tools::BindCurrentWorkspaceTool));

crates/mcpmux-gateway/src/services/meta_tools/tools.rs

@@ -110,6 +110,117 @@ impl MetaTool for ListAllToolsTool {
     }
 }
 
+// ---------------------------------------------------------------------------
+// mcpmux_search_tools — read
+// ---------------------------------------------------------------------------
+
+pub struct SearchToolsTool;
+
+/// Default cap on returned matches — keeps the payload (and the agent's token
+/// spend) bounded when a broad query matches many tools.
+const SEARCH_TOOLS_DEFAULT_LIMIT: usize = 25;
+/// Hard ceiling so a caller can't request an unbounded dump via `limit`.
+const SEARCH_TOOLS_MAX_LIMIT: usize = 100;
+
+#[async_trait]
+impl MetaTool for SearchToolsTool {
+    fn name(&self) -> &'static str {
+        "mcpmux_search_tools"
+    }
+
+    fn description(&self) -> &'static str {
+        "Search the tools installed in the caller's resolved Space by keyword, \
+         without the current FeatureSet filter applied. Prefer this over \
+         `mcpmux_list_all_tools` when you know roughly what you're looking for — \
+         it returns only matches, so it's far cheaper than dumping the whole \
+         catalog. `query` is matched case-insensitively against each tool's \
+         qualified name, description, and server id. Optional `limit` (default \
+         25, max 100). Returns an array of \
+         {server_id, qualified_name, description, available}."
+    }
+
+    fn input_schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "required": ["query"],
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "keyword(s) matched against tool name, description, and server id"
+                },
+                "limit": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": SEARCH_TOOLS_MAX_LIMIT,
+                    "description": "max matches to return (default 25)"
+                }
+            }
+        })
+    }
+
+    async fn call(&self, call: MetaToolCall<'_>) -> Result<CallToolResult, MetaToolError> {
+        let query = opt_str_arg(&call.args, "query").ok_or_else(|| {
+            MetaToolError::InvalidArgument("search requires a non-empty `query`".into())
+        })?;
+        let needle = query.to_lowercase();
+
+        // `limit`: clamp to [1, MAX]; fall back to the default when absent or
+        // not a positive integer.
+        let limit = call
+            .args
+            .get("limit")
+            .and_then(|v| v.as_u64())
+            .map(|n| (n as usize).clamp(1, SEARCH_TOOLS_MAX_LIMIT))
+            .unwrap_or(SEARCH_TOOLS_DEFAULT_LIMIT);
+
+        let space_id = caller_space_id(&call).await?;
+        let features = call
+            .ctx
+            .server_feature_repo
+            .list_for_space(&space_id.to_string())
+            .await?;
+
+        let mut matches: Vec<&ServerFeature> = features
+            .iter()
+            .filter(|f| f.feature_type == FeatureType::Tool)
+            .filter(|f| {
+                f.qualified_name().to_lowercase().contains(&needle)
+                    || f.server_id.to_lowercase().contains(&needle)
+                    || f.description
+                        .as_deref()
+                        .map(|d| d.to_lowercase().contains(&needle))
+                        .unwrap_or(false)
+            })
+            .collect();
+
+        // Stable, predictable ordering before truncating to `limit`.
+        matches.sort_by_key(|f| f.qualified_name());
+        let total = matches.len();
+        let truncated = total > limit;
+
+        let tools: Vec<_> = matches
+            .into_iter()
+            .take(limit)
+            .map(|f| {
+                json!({
+                    "server_id": f.server_id,
+                    "qualified_name": f.qualified_name(),
+                    "description": f.description,
+                    "available": f.is_available,
+                })
+            })
+            .collect();
+
+        Ok(text_result(json!({
+            "query": query,
+            "match_count": total,
+            "returned": tools.len(),
+            "truncated": truncated,
+            "tools": tools,
+        })))
+    }
+}
+
 // ---------------------------------------------------------------------------
 // mcpmux_list_feature_sets — read
 // ---------------------------------------------------------------------------

tests/rust/tests/integration/meta_tools.rs

@@ -266,9 +266,109 @@ async fn list_feature_sets_returns_space_contents() {
     assert_eq!(sets.len(), 3, "Default + 2 custom expected");
 }
 
+#[tokio::test(flavor = "multi_thread")]
+async fn search_tools_matches_name_server_and_description() {
+    let f = Fixture::new().await;
+
+    // By qualified name / server id.
+    let by_name = Fixture::result_json(
+        &f.registry
+            .call(
+                "mcpmux_search_tools",
+                &f.client_id,
+                Some(&f.session_id),
+                json!({ "query": "github" }),
+            )
+            .await
+            .unwrap(),
+    );
+    assert_eq!(by_name.get("match_count").unwrap().as_u64().unwrap(), 1);
+    let tools = by_name.get("tools").unwrap().as_array().unwrap();
+    assert_eq!(
+        tools[0].get("qualified_name").unwrap().as_str().unwrap(),
+        "github_create_issue"
+    );
+
+    // By description text ("Deploy to Firebase").
+    let by_desc = Fixture::result_json(
+        &f.registry
+            .call(
+                "mcpmux_search_tools",
+                &f.client_id,
+                Some(&f.session_id),
+                json!({ "query": "deploy" }),
+            )
+            .await
+            .unwrap(),
+    );
+    let desc_tools = by_desc.get("tools").unwrap().as_array().unwrap();
+    assert_eq!(desc_tools.len(), 1);
+    assert_eq!(
+        desc_tools[0]
+            .get("qualified_name")
+            .unwrap()
+            .as_str()
+            .unwrap(),
+        "firebase_deploy"
+    );
+
+    // No match → empty, not an error.
+    let none = Fixture::result_json(
+        &f.registry
+            .call(
+                "mcpmux_search_tools",
+                &f.client_id,
+                Some(&f.session_id),
+                json!({ "query": "zzzznotathing" }),
+            )
+            .await
+            .unwrap(),
+    );
+    assert_eq!(none.get("match_count").unwrap().as_u64().unwrap(), 0);
+    assert!(none.get("tools").unwrap().as_array().unwrap().is_empty());
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn search_tools_requires_query() {
+    let f = Fixture::new().await;
+    let res = f
+        .call_tool_as_handler_would("mcpmux_search_tools", json!({}))
+        .await;
+    assert!(Fixture::is_error(&res));
+    assert_eq!(
+        Fixture::result_json(&res)
+            .get("error")
+            .unwrap()
+            .as_str()
+            .unwrap(),
+        "invalid_argument"
+    );
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn search_tools_caps_results_at_limit_and_flags_truncation() {
+    let f = Fixture::new().await;
+    // "e" appears in both seeded tools' names/descriptions → 2 matches.
+    let body = Fixture::result_json(
+        &f.registry
+            .call(
+                "mcpmux_search_tools",
+                &f.client_id,
+                Some(&f.session_id),
+                json!({ "query": "e", "limit": 1 }),
+            )
+            .await
+            .unwrap(),
+    );
+    assert_eq!(body.get("match_count").unwrap().as_u64().unwrap(), 2);
+    assert_eq!(body.get("returned").unwrap().as_u64().unwrap(), 1);
+    assert!(body.get("truncated").unwrap().as_bool().unwrap());
+    assert_eq!(body.get("tools").unwrap().as_array().unwrap().len(), 1);
+}
+
 // `describe_resolution` and `describe_workspace` were both removed at the
-// user's request — the read surface is now just `list_all_tools` and
-// `list_feature_sets`. Behavior previously asserted here is covered by
+// user's request — the read surface is now `list_all_tools`, `search_tools`,
+// and `list_feature_sets`. Behavior previously asserted here is covered by
 // `FeatureSetResolverService`'s own tests in
 // `tests/rust/tests/integration/feature_set_resolver.rs`.
 
@@ -693,6 +793,7 @@ async fn registry_advertises_every_default_tool_with_annotations() {
     let names: Vec<_> = tools.iter().map(|t| t.name.to_string()).collect();
     for expected in [
         "mcpmux_list_all_tools",
+        "mcpmux_search_tools",
         "mcpmux_list_feature_sets",
         "mcpmux_manage_feature_set",
         "mcpmux_bind_current_workspace",