Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

Honor Code Mode search limits after BM25 ranking (#5715)

Winorenee713912c709
diff --git a/docs/servers/transforms/code-mode.mdx b/docs/servers/transforms/code-mode.mdx
index c8108162d..74f6e833e 100644
--- a/docs/servers/transforms/code-mode.mdx
+++ b/docs/servers/transforms/code-mode.mdx
@@ -133,7 +133,7 @@ CodeMode ships with four built-in discovery tools: `Search`, `GetSchemas`, `GetT
Search results include an annotation like `"2 of 10 tools:"` when the result set is smaller than the full catalog, so the LLM knows there are more tools to discover with different queries.
-You can cap result count with `default_limit`. The LLM can also override the limit per call. This is useful for large catalogs where you want to keep search results focused:
+By default, `Search` returns all matching tools (`default_limit=None`). You can cap the result count with `default_limit` to keep large catalogs focused. The LLM can override this limit per call, including requesting more results or passing `limit=None` to return all matches:
```python
Search(default_limit=5) # return at most 5 results per search
diff --git a/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py b/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py
index 8ce99a591..af774e3bf 100644
--- a/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py
+++ b/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py
@@ -1,6 +1,7 @@
import asyncio
import importlib
import json
+import sys
from collections.abc import Awaitable, Callable, Sequence
from typing import TYPE_CHECKING, Annotated, Any, Literal, Protocol
@@ -375,7 +376,8 @@ class Search:
if search_fn is None:
from fastmcp.server.transforms.search.bm25 import BM25SearchTransform
- _bm25 = BM25SearchTransform(max_results=default_limit or 50)
+ # Search applies the per-call limit after ranking all matches.
+ _bm25 = BM25SearchTransform(max_results=sys.maxsize)
search_fn = _bm25._search
self._search_fn = search_fn
self._name = name
@@ -421,7 +423,9 @@ class Search:
]
results = await search_fn(tools, query)
if limit is not None:
- results = results[:limit]
+ # A limit is a maximum count, not a slice offset: clamp negatives
+ # so ``limit=-1`` does not mean "all but the last match".
+ results = results[: max(limit, 0)]
rendered = _render_tools(results, detail)
if len(results) < catalog_size and detail != "full":
n = len(results)
diff --git a/tests/experimental/transforms/test_code_mode_search_limits.py b/tests/experimental/transforms/test_code_mode_search_limits.py
new file mode 100644
index 000000000..045c3a772
--- /dev/null
+++ b/tests/experimental/transforms/test_code_mode_search_limits.py
@@ -0,0 +1,100 @@
+"""Code Mode must apply result limits after ranking the complete catalog."""
+
+import json
+
+import pytest
+
+from fastmcp import Client, FastMCP
+from fastmcp.experimental.transforms.code_mode import CodeMode, Search
+from fastmcp.tools import Tool
+
+CATALOG_SIZE = 60
+
+
+def _ranked_catalog() -> FastMCP:
+ """Build a catalog whose BM25 ranking is the reverse of its registration order.
+
+ Every tool repeats the query token a different number of times, so no two
+ scores tie. The best match is therefore registered last, which makes the
+ difference between ranking-then-slicing and slicing-then-ranking visible in
+ the returned names instead of hiding behind catalogue order.
+ """
+ server = FastMCP("Search limits")
+
+ def add_one(x: int) -> int:
+ """Add one to a number."""
+ return x + 1
+
+ for index in range(CATALOG_SIZE):
+ server.add_tool(
+ Tool.from_function(
+ add_one,
+ name=f"add_{index:02d}",
+ description="Add one to a number. " + "add " * index,
+ )
+ )
+ return server
+
+
+# Relevance rises with the registration index, so this is the ranked order.
+_RANKED_NAMES = [f"add_{index:02d}" for index in range(CATALOG_SIZE - 1, -1, -1)]
+
+
+ "default_limit, override, expected_count",
+ [
+ (None, {}, CATALOG_SIZE),
+ (None, {"limit": 55}, 55),
+ (None, {"limit": 0}, 0),
+ (5, {}, 5),
+ (5, {"limit": 55}, 55),
+ (5, {"limit": None}, CATALOG_SIZE),
+ (55, {}, 55),
+ ],
+)
+async def test_search_applies_limits_after_ranking(
+ default_limit: int | None,
+ override: dict[str, int | None],
+ expected_count: int,
+) -> None:
+ server = _ranked_catalog()
+ server.add_transform(
+ CodeMode(discovery_tools=[Search(default_limit=default_limit)])
+ )
+
+ async with Client(server) as client:
+ result = await client.call_tool(
+ "search", {"query": "add", "detail": "full", **override}
+ )
+
+ matches = json.loads(result.data)
+ assert [match["name"] for match in matches] == _RANKED_NAMES[:expected_count]
+
+
[email protected]("limit", [-1, -5, -60, -61])
+async def test_search_reads_a_negative_limit_as_a_count(limit: int) -> None:
+ """A limit is a maximum result count, so it can never be negative.
+
+ Python's slice semantics would otherwise read ``limit=-1`` as "all but the
+ last one", which is a fine reading of a slice and a wrong reading of a cap.
+ """
+ server = _ranked_catalog()
+ server.add_transform(CodeMode(discovery_tools=[Search()]))
+
+ async with Client(server) as client:
+ result = await client.call_tool(
+ "search", {"query": "add", "detail": "full", "limit": limit}
+ )
+
+ assert json.loads(result.data) == []
+
+
+async def test_search_first_result_is_the_best_match_registered_last() -> None:
+ """Ranking decides what survives a small limit, not registration order."""
+ server = _ranked_catalog()
+ server.add_transform(CodeMode(discovery_tools=[Search(default_limit=3)]))
+
+ async with Client(server) as client:
+ result = await client.call_tool("search", {"query": "add", "detail": "full"})
+
+ assert [match["name"] for match in json.loads(result.data)] == _RANKED_NAMES[:3]