fix(mcp): cap search_metadata response size to prevent LLM context overflow (#28383)

* fix(mcp): cap search_metadata response size and truncate columnNames

* fix(mcp): remove column truncation, guide LLM to use smaller page sizes

Author: Shreyansh100704

openmetadata-mcp/src/main/java/org/openmetadata/mcp/tools/SearchMetadataTool.java

@@ -31,6 +31,7 @@ public class SearchMetadataTool implements McpTool {
   private static final int MAX_ALLOWED_AGGREGATION_BUCKETS = 50;
   private static final int DESCRIPTION_MAX_LENGTH = 500;
   private static final int DESCRIPTION_TRUNCATE_LENGTH = 450;
+  private static final int MAX_RESPONSE_CHARS = 100_000;
 
   private static final List<String> ESSENTIAL_FIELDS_ONLY =
       List.of(
@@ -332,11 +333,48 @@ static Map<String, Object> buildEnhancedSearchResponse(
       result.put(
           "message",
           String.format(
-              "Found %d total results, showing first %d. Use pagination or refine your search for more specific results, you can call these 3 times by yourself with pagination , and then only if the user ask for more paginate.",
+              "Found %d total results, showing first %d. "
+                  + "There are many matching assets. Are you looking for something specific? "
+                  + "Try narrowing with a service name, schema name, or more specific search term.",
               totalResults, cleanedResults.size()));
       result.put("hasMore", true);
     }
 
+    try {
+      String serialized = JsonUtils.pojoToJson(result);
+      LOG.debug(
+          "[MCP] search_metadata response size: {} chars for query '{}'",
+          serialized.length(),
+          query);
+      if (serialized.length() > MAX_RESPONSE_CHARS) {
+        int targetCount =
+            Math.min(
+                Math.max(
+                    1,
+                    (int)
+                        (cleanedResults.size() * (MAX_RESPONSE_CHARS * 0.8) / serialized.length())),
+                cleanedResults.size());
+        List<Map<String, Object>> trimmed = new ArrayList<>(cleanedResults.subList(0, targetCount));
+        LOG.warn(
+            "[MCP] search_metadata response trimmed: {} chars -> {} results (was {})",
+            serialized.length(),
+            trimmed.size(),
+            cleanedResults.size());
+        result.put("results", trimmed);
+        result.put("returnedCount", trimmed.size());
+        result.put("hasMore", true);
+        result.put(
+            "message",
+            String.format(
+                "Response exceeded %d characters and was trimmed to %d of %d results. "
+                    + "There are many matching assets. Are you looking for something specific? "
+                    + "Try narrowing with a service name, schema, or specific name.",
+                MAX_RESPONSE_CHARS, trimmed.size(), totalResults));
+      }
+    } catch (RuntimeException e) {
+      LOG.warn("Failed to check response size for query '{}': {}", query, e.getMessage());
+    }
+
     return result;
   }
 

openmetadata-mcp/src/main/resources/json/data/mcp/tools.json

@@ -26,7 +26,7 @@
           },
           "size": {
             "type": "integer",
-            "description": "Number of results to return. Default is 10, we can iteratively page through results by increasing 'from'. Maximum allowed is 50.",
+            "description": "Number of results to return. Default is 10. For broad or generic queries (e.g. 'show all tables'), keep size small (5-10), as results are summaries; use get_entity_details for full entity info. Only increase size when the query is specific enough that results will be narrow and focused. Maximum allowed is 50.",
             "default": 10
           },
           "includeDeleted": {
@@ -73,7 +73,7 @@
           {
             "description": "Simple search with pagination",
             "query": "tables",
-            "size": 20,
+            "size": 10,
             "from": 0
           },
           {

openmetadata-mcp/src/test/java/org/openmetadata/mcp/tools/SearchMetadataAggregationTest.java

@@ -242,4 +242,78 @@ private Map<String, Object> createEmptyHits() {
     hits.put("total", total);
     return hits;
   }
+
+  @Test
+  void testResponseTrimmedWhenExceedingCharLimit() {
+    // 50 results each with 200 columns (~50 chars each) => ~500k chars, well over the 100k cap
+    Map<String, Object> searchResponse = createSearchResponseWithLargeResults(50, 200);
+
+    Map<String, Object> result =
+        SearchMetadataTool.buildEnhancedSearchResponse(
+            searchResponse, "*", 50, Collections.emptyList(), false, 10);
+
+    @SuppressWarnings("unchecked")
+    List<Map<String, Object>> results = (List<Map<String, Object>>) result.get("results");
+    assertTrue(results.size() < 50, "Results should be trimmed below requested 50");
+    assertEquals(true, result.get("hasMore"), "hasMore must be true when trimmed by size cap");
+    assertEquals(results.size(), result.get("returnedCount"));
+    String message = (String) result.get("message");
+    assertTrue(message.contains("trimmed"), "Message should mention trimming");
+  }
+
+  @Test
+  void testResponseNotTrimmedWhenUnderCharLimit() {
+    // 5 results with 2 columns each — well under 100k
+    Map<String, Object> searchResponse = createSearchResponseWithLargeResults(5, 2);
+
+    Map<String, Object> result =
+        SearchMetadataTool.buildEnhancedSearchResponse(
+            searchResponse, "*", 50, Collections.emptyList(), false, 10);
+
+    @SuppressWarnings("unchecked")
+    List<Map<String, Object>> results = (List<Map<String, Object>>) result.get("results");
+    assertEquals(5, results.size(), "Results should not be trimmed when under char limit");
+  }
+
+  @Test
+  void testResponseTrimmedToAtLeastOneResult() {
+    // Single result with enough columns to exceed 100k on its own
+    Map<String, Object> searchResponse = createSearchResponseWithLargeResults(1, 3000);
+
+    Map<String, Object> result =
+        SearchMetadataTool.buildEnhancedSearchResponse(
+            searchResponse, "*", 50, Collections.emptyList(), false, 10);
+
+    @SuppressWarnings("unchecked")
+    List<Map<String, Object>> results = (List<Map<String, Object>>) result.get("results");
+    assertEquals(1, results.size(), "At least one result must always be returned");
+  }
+
+  private Map<String, Object> createSearchResponseWithLargeResults(int count, int columnCount) {
+    Map<String, Object> response = new HashMap<>();
+
+    List<Map<String, Object>> hits = new ArrayList<>();
+    for (int i = 0; i < count; i++) {
+      Map<String, Object> source = new HashMap<>();
+      source.put("name", "table_" + i);
+      source.put("fullyQualifiedName", "service.db.schema.table_" + i);
+      source.put("entityType", "table");
+      List<String> columnNames = new ArrayList<>();
+      for (int c = 0; c < columnCount; c++) {
+        columnNames.add("column_with_long_name_to_increase_payload_size_" + c);
+      }
+      source.put("columnNames", columnNames);
+      Map<String, Object> hit = new HashMap<>();
+      hit.put("_source", source);
+      hits.add(hit);
+    }
+
+    Map<String, Object> total = new HashMap<>();
+    total.put("value", count);
+    Map<String, Object> hitsObj = new HashMap<>();
+    hitsObj.put("hits", hits);
+    hitsObj.put("total", total);
+    response.put("hits", hitsObj);
+    return response;
+  }
 }