fix(gateway): improve meta-tool DX for ACL, schema batch, and max_bytes

list_all_tools now exposes invokable vs server_available with counts;
get_tool_schema accepts array and JSON-encoded array forms and reports
missing names; invoke filter applies max_bytes to JSON arrays without max_rows.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>

Author: crimsonsunset

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

@@ -378,11 +378,11 @@ fn shape_array(items: Vec<Value>, filter: &InvokeResultFilter, data_key: &str) -
     let filtered_items = apply_fields_filter(items, filter);
 
     let Some(max_rows) = filter.max_rows else {
-        return Value::Array(filtered_items);
+        return enforce_byte_limit(Value::Array(filtered_items), filter);
     };
 
     if total <= max_rows {
-        return Value::Array(filtered_items);
+        return enforce_byte_limit(Value::Array(filtered_items), filter);
     }
 
     let sample_size = if filter.is_summary() {
@@ -662,6 +662,20 @@ mod tests {
         assert_eq!(filter.max_bytes, None);
     }
 
+    #[test]
+    fn max_bytes_only_truncates_top_level_json_array() {
+        let items: Vec<Value> = (0..50)
+            .map(|i| json!({ "id": i, "label": format!("row-{i}-padding") }))
+            .collect();
+        let filter = InvokeResultFilter {
+            max_bytes: Some(512),
+            ..Default::default()
+        };
+        let shaped = shape_json_value(Value::Array(items), &filter);
+        assert_eq!(shaped.get("truncated"), Some(&json!(true)));
+        assert!(shaped.get("total").and_then(|v| v.as_u64()).unwrap_or(0) > 512);
+    }
+
     #[test]
     fn plain_text_byte_trunc_includes_metadata() {
         let text = "x".repeat(100);

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

@@ -111,10 +111,11 @@ impl MetaTool for ListAllToolsTool {
     }
 
     fn description(&self) -> &'static str {
-        "List every tool installed in the caller's resolved Space, without \
-         the current FeatureSet filter applied. Use this to see what the \
-         workspace could expose before composing a custom FeatureSet. \
-         Returns an array of {server_id, qualified_name, description, available}."
+        "Operator/diagnostic: list every tool installed in the caller's resolved \
+         Space (ignores FeatureSet filter on the roster). Each entry includes \
+         server_available (seen on the connected server) and invokable (callable \
+         via mcpmux_invoke_tool with current grants). Agents should prefer \
+         mcpmux_search_tools for discovery — only invokable tools can be invoked."
     }
 
     fn input_schema(&self) -> Value {
@@ -130,8 +131,26 @@ impl MetaTool for ListAllToolsTool {
     }
 
     async fn call(&self, call: MetaToolCall<'_>) -> Result<CallToolResult, MetaToolError> {
+        let resolved = caller_resolution(&call).await?;
         let space_id = caller_space_id(&call).await?;
         let server_filter = call.args.get("server_id").and_then(|v| v.as_str());
+
+        let invokable = call
+            .ctx
+            .feature_service
+            .get_invokable_tools_for_grants(
+                &space_id.to_string(),
+                &resolved.feature_set_ids,
+                call.session_id,
+            )
+            .await
+            .map_err(|e| MetaToolError::Internal(e.to_string()))?;
+        let invokable_names: HashSet<String> = invokable
+            .iter()
+            .filter(|f| f.feature_type == FeatureType::Tool)
+            .map(|f| f.qualified_name())
+            .collect();
+
         let features = call
             .ctx
             .server_feature_repo
@@ -142,15 +161,26 @@ impl MetaTool for ListAllToolsTool {
             .filter(|f| f.feature_type == FeatureType::Tool)
             .filter(|f| server_filter.is_none_or(|sid| f.server_id == sid))
             .map(|f| {
+                let qualified_name = f.qualified_name();
                 json!({
                     "server_id": f.server_id,
-                    "qualified_name": f.qualified_name(),
+                    "qualified_name": qualified_name,
                     "description": f.description,
-                    "available": f.is_available,
+                    "server_available": f.is_available,
+                    "invokable": invokable_names.contains(&qualified_name),
                 })
             })
             .collect();
-        Ok(text_result(json!({ "tools": tools })))
+        let total_invokable = tools
+            .iter()
+            .filter(|t| t.get("invokable") == Some(&json!(true)))
+            .count();
+        Ok(text_result(json!({
+            "tools": tools,
+            "total_installed": tools.len(),
+            "total_invokable": total_invokable,
+            "hint": "Use mcpmux_search_tools for agent discovery. Only invokable tools can be invoked with current FeatureSet grants.",
+        })))
     }
 }
 
@@ -435,6 +465,47 @@ impl MetaTool for SearchToolsTool {
 // mcpmux_get_tool_schema — read
 // ---------------------------------------------------------------------------
 
+/// Parse the `tools` argument from `mcpmux_get_tool_schema` call args.
+///
+/// Accepts a qualified name string, a string array, or a JSON-encoded array
+/// string (common when agents double-serialize through MCP clients).
+fn parse_tool_schema_names(value: Option<&Value>) -> Result<Vec<String>, MetaToolError> {
+    let Some(value) = value else {
+        return Err(MetaToolError::InvalidArgument(
+            "missing or invalid `tools` — expected string or string array".into(),
+        ));
+    };
+
+    match value {
+        Value::String(s) => {
+            if let Ok(Value::Array(arr)) = serde_json::from_str(s) {
+                return names_from_json_array(&arr);
+            }
+            Ok(vec![s.clone()])
+        }
+        Value::Array(arr) => names_from_json_array(arr),
+        _ => Err(MetaToolError::InvalidArgument(
+            "missing or invalid `tools` — expected string or string array".into(),
+        )),
+    }
+}
+
+/// Collect non-empty qualified tool names from a JSON string array.
+fn names_from_json_array(arr: &[Value]) -> Result<Vec<String>, MetaToolError> {
+    let names: Vec<String> = arr
+        .iter()
+        .filter_map(|v| v.as_str().map(str::trim))
+        .filter(|s| !s.is_empty())
+        .map(str::to_string)
+        .collect();
+    if names.is_empty() {
+        return Err(MetaToolError::InvalidArgument(
+            "`tools` must contain at least one qualified name".into(),
+        ));
+    }
+    Ok(names)
+}
+
 pub struct GetToolSchemaTool;
 
 #[async_trait]
@@ -445,8 +516,10 @@ impl MetaTool for GetToolSchemaTool {
 
     fn description(&self) -> &'static str {
         "Load input schemas for one or more qualified tool names before \
-         invoking via mcpmux_invoke_tool. Pass tools as a string or array. \
-         Set compact: true to omit descriptions."
+         invoking via mcpmux_invoke_tool. Pass tools as a single qualified \
+         name string or a string array (e.g. [\"github_list_issues\"]). \
+         Set compact: true to omit descriptions. Tools must be invokable \
+         with current grants — use mcpmux_search_tools to discover names."
     }
 
     fn input_schema(&self) -> Value {
@@ -469,24 +542,7 @@ impl MetaTool for GetToolSchemaTool {
         let resolved = caller_resolution(&call).await?;
         let space_id = caller_space_id(&call).await?;
 
-        let tool_names: Vec<String> = match call.args.get("tools") {
-            Some(Value::String(s)) => vec![s.clone()],
-            Some(Value::Array(arr)) => arr
-                .iter()
-                .filter_map(|v| v.as_str().map(String::from))
-                .collect(),
-            _ => {
-                return Err(MetaToolError::InvalidArgument(
-                    "missing or invalid `tools` — expected string or string array".into(),
-                ));
-            }
-        };
-
-        if tool_names.is_empty() {
-            return Err(MetaToolError::InvalidArgument(
-                "`tools` must contain at least one qualified name".into(),
-            ));
-        }
+        let tool_names = parse_tool_schema_names(call.args.get("tools"))?;
 
         let compact = call
             .args
@@ -518,7 +574,32 @@ impl MetaTool for GetToolSchemaTool {
             compact,
         );
 
-        Ok(text_result(json!({ "schemas": schemas })))
+        let found_names: HashSet<String> = schemas
+            .iter()
+            .filter_map(|s| {
+                s.get("qualified_name")
+                    .and_then(|v| v.as_str())
+                    .map(str::to_string)
+            })
+            .collect();
+        let missing: Vec<&String> = tool_names
+            .iter()
+            .filter(|name| !found_names.contains(*name))
+            .collect();
+
+        if missing.is_empty() {
+            return Ok(text_result(json!({ "schemas": schemas })));
+        }
+
+        let missing_list: Vec<&str> = missing.iter().map(|s| s.as_str()).collect();
+        Ok(text_result(json!({
+            "schemas": schemas,
+            "missing": missing_list,
+            "message": format!(
+                "{} tool(s) not invokable or unknown with current grants → use mcpmux_search_tools to discover allowed names",
+                missing.len()
+            ),
+        })))
     }
 }
 

tests/rust/tests/integration/meta_gateway_invoke.rs

@@ -645,3 +645,156 @@ async fn direct_backend_call_gate_allows_surfaced_only() {
     assert!(is_surfaced("github_list_issues"));
     assert!(!is_surfaced("github_get_me"));
 }
+
+#[tokio::test(flavor = "multi_thread")]
+async fn list_all_tools_marks_invokable_against_acl() {
+    let f = Fixture::new().await;
+
+    let list_issues = f
+        .server_feature_repo
+        .list_for_space(&f.space_id.to_string())
+        .await
+        .unwrap()
+        .into_iter()
+        .find(|feat| feat.feature_name == "list_issues")
+        .unwrap();
+
+    let mut create_issue = ServerFeature::tool(f.space_id, "github", "create_issue");
+    create_issue.description = Some("Create an issue".into());
+    f.server_feature_repo.upsert(&create_issue).await.unwrap();
+
+    let mut partial_fs = FeatureSet::new_custom("Partial GitHub", f.space_id.to_string());
+    partial_fs.members.push(FeatureSetMember {
+        id: Uuid::new_v4().to_string(),
+        feature_set_id: partial_fs.id.clone(),
+        member_type: MemberType::Feature,
+        member_id: list_issues.id.to_string(),
+        mode: MemberMode::Include,
+        surfaced: false,
+    });
+    f.feature_set_repo.create(&partial_fs).await.unwrap();
+    f.grant_feature_set(&partial_fs.id).await;
+    f.session_overrides.enable(&f.session_id, "github");
+
+    let result = f
+        .call("mcpmux_list_all_tools", json!({ "server_id": "github" }))
+        .await;
+    let body = Fixture::result_json(&result);
+    assert_eq!(body.get("total_installed").and_then(|v| v.as_u64()), Some(2));
+    assert_eq!(body.get("total_invokable").and_then(|v| v.as_u64()), Some(1));
+
+    let tools = body.get("tools").unwrap().as_array().unwrap();
+    let list_row = tools
+        .iter()
+        .find(|t| t.get("qualified_name") == Some(&json!("github_list_issues")))
+        .expect("list_issues in catalog");
+    let create_row = tools
+        .iter()
+        .find(|t| t.get("qualified_name") == Some(&json!("github_create_issue")))
+        .expect("create_issue in catalog");
+    assert_eq!(list_row.get("invokable"), Some(&json!(true)));
+    assert_eq!(create_row.get("invokable"), Some(&json!(false)));
+    assert_eq!(list_row.get("server_available"), Some(&json!(true)));
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn get_tool_schema_accepts_string_array() {
+    let f = Fixture::new().await;
+    f.grant_github_feature_set().await;
+    f.session_overrides.enable(&f.session_id, "github");
+
+    let result = f
+        .call(
+            "mcpmux_get_tool_schema",
+            json!({ "tools": ["github_list_issues"] }),
+        )
+        .await;
+    let body = Fixture::result_json(&result);
+    let schemas = body.get("schemas").unwrap().as_array().unwrap();
+    assert_eq!(schemas.len(), 1);
+    assert_eq!(
+        schemas[0].get("qualified_name"),
+        Some(&json!("github_list_issues"))
+    );
+    assert!(body.get("missing").is_none());
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn get_tool_schema_accepts_json_encoded_array_string() {
+    let f = Fixture::new().await;
+    f.grant_github_feature_set().await;
+    f.session_overrides.enable(&f.session_id, "github");
+
+    let result = f
+        .call(
+            "mcpmux_get_tool_schema",
+            json!({ "tools": "[\"github_list_issues\"]" }),
+        )
+        .await;
+    let body = Fixture::result_json(&result);
+    let schemas = body.get("schemas").unwrap().as_array().unwrap();
+    assert_eq!(schemas.len(), 1);
+    assert_eq!(
+        schemas[0].get("qualified_name"),
+        Some(&json!("github_list_issues"))
+    );
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn get_tool_schema_reports_missing_tools() {
+    let f = Fixture::new().await;
+    f.grant_github_feature_set().await;
+    f.session_overrides.enable(&f.session_id, "github");
+
+    let result = f
+        .call(
+            "mcpmux_get_tool_schema",
+            json!({ "tools": ["github_list_issues", "github_create_issue"] }),
+        )
+        .await;
+    let body = Fixture::result_json(&result);
+    let schemas = body.get("schemas").unwrap().as_array().unwrap();
+    assert_eq!(schemas.len(), 1);
+    let missing = body.get("missing").unwrap().as_array().unwrap();
+    assert_eq!(missing, &[json!("github_create_issue")]);
+    assert!(body.get("message").and_then(|m| m.as_str()).is_some());
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn invoke_max_bytes_truncates_json_array_without_max_rows() {
+    let rows: Vec<Value> = (0..40)
+        .map(|i| json!({ "id": i, "label": format!("row-{i}-padding-value") }))
+        .collect();
+    let payload = json!({ "items": rows });
+    let backend_result = ToolCallResult {
+        content: vec![json!({
+            "type": "text",
+            "text": payload.to_string(),
+        })],
+        structured_content: None,
+        is_error: false,
+    };
+    let invoke_backend = CannedInvokeBackend::new()
+        .with_response("github_list_issues", backend_result)
+        .into_arc();
+
+    let f = Fixture::with_invoke_backend(Some(invoke_backend)).await;
+    f.grant_github_feature_set().await;
+    f.session_overrides.enable(&f.session_id, "github");
+
+    let result = f
+        .call(
+            "mcpmux_invoke_tool",
+            json!({
+                "server_id": "github",
+                "tool": "list_issues",
+                "args": { "owner": "mcpmux", "repo": "mcp-mux" },
+                "filter": { "max_bytes": 512 }
+            }),
+        )
+        .await;
+
+    assert!(!result.is_error.unwrap_or(true));
+    let body = Fixture::result_json(&result);
+    assert_eq!(body.get("truncated"), Some(&json!(true)));
+}