Skip to content

The agent that grows with you

fix(tools): tool_search catalog keeps small servers' descriptions next to a huge one

Teknium079b38cd0734
diff --git a/tests/fixtures/prompt_surface/surfaces.json b/tests/fixtures/prompt_surface/surfaces.json
index 6ede7e4d4de..4eb511478e1 100644
--- a/tests/fixtures/prompt_surface/surfaces.json
+++ b/tests/fixtures/prompt_surface/surfaces.json
@@ -1,11 +1,11 @@
{
"cli-code.claude": {
"prompt_tokens": {
- "context": 134,
- "stable": 1829,
- "volatile": 1528
+ "context": 249,
+ "stable": 1935,
+ "volatile": 1813
},
- "tool_tokens": 11263,
+ "tool_tokens": 11468,
"tools": [
"browser_cdp",
"browser_dialog",
@@ -35,10 +35,10 @@
"cli.claude": {
"prompt_tokens": {
"context": 0,
- "stable": 1225,
- "volatile": 1528
+ "stable": 1445,
+ "volatile": 1813
},
- "tool_tokens": 11263,
+ "tool_tokens": 11468,
"tools": [
"browser_cdp",
"browser_dialog",
@@ -68,10 +68,10 @@
"cli.gemini": {
"prompt_tokens": {
"context": 0,
- "stable": 1646,
- "volatile": 1527
+ "stable": 1866,
+ "volatile": 1811
},
- "tool_tokens": 11263,
+ "tool_tokens": 11468,
"tools": [
"browser_cdp",
"browser_dialog",
@@ -101,10 +101,10 @@
"cli.gpt": {
"prompt_tokens": {
"context": 0,
- "stable": 2420,
- "volatile": 1524
+ "stable": 2640,
+ "volatile": 1809
},
- "tool_tokens": 11419,
+ "tool_tokens": 11624,
"tools": [
"browser_cdp",
"browser_dialog",
@@ -134,10 +134,10 @@
"cli.hermes": {
"prompt_tokens": {
"context": 0,
- "stable": 1225,
- "volatile": 1528
+ "stable": 1445,
+ "volatile": 1813
},
- "tool_tokens": 11263,
+ "tool_tokens": 11468,
"tools": [
"browser_cdp",
"browser_dialog",
@@ -167,10 +167,10 @@
"cron.claude": {
"prompt_tokens": {
"context": 0,
- "stable": 1211,
- "volatile": 1528
+ "stable": 1317,
+ "volatile": 1813
},
- "tool_tokens": 11263,
+ "tool_tokens": 11468,
"tools": [
"browser_cdp",
"browser_dialog",
@@ -200,10 +200,10 @@
"desktop.claude": {
"prompt_tokens": {
"context": 0,
- "stable": 1473,
- "volatile": 1529
+ "stable": 1579,
+ "volatile": 1814
},
- "tool_tokens": 11929,
+ "tool_tokens": 12124,
"tools": [
"browser_cdp",
"browser_dialog",
@@ -234,10 +234,10 @@
"discord.claude": {
"prompt_tokens": {
"context": 0,
- "stable": 1244,
- "volatile": 1529
+ "stable": 1349,
+ "volatile": 1814
},
- "tool_tokens": 11263,
+ "tool_tokens": 11468,
"tools": [
"browser_cdp",
"browser_dialog",
@@ -267,10 +267,10 @@
"telegram.claude": {
"prompt_tokens": {
"context": 0,
- "stable": 1276,
- "volatile": 1529
+ "stable": 1382,
+ "volatile": 1814
},
- "tool_tokens": 11263,
+ "tool_tokens": 11468,
"tools": [
"browser_cdp",
"browser_dialog",
diff --git a/tests/fixtures/prompt_surface/tools/tool_search.desktop.claude.json b/tests/fixtures/prompt_surface/tools/tool_search.desktop.claude.json
index a2ac6d783f0..0513f2ceeb8 100644
--- a/tests/fixtures/prompt_surface/tools/tool_search.desktop.claude.json
+++ b/tests/fixtures/prompt_surface/tools/tool_search.desktop.claude.json
@@ -1,5 +1,5 @@
{
- "description": "Search 19 additional tools that are loaded on demand. Send one keyword query per capability you need; returns matching tool names and descriptions. Then `tool_describe` loads schemas and `tool_call` invokes. Tools already in your tool list need no search. `connectors__` names are tools of the user's app accounts (Gmail, Linear, ...); `manage_connections` checks or authorizes an account.\n\nEvery tool listed below exists: never call it unavailable, and go straight to `tool_describe` when you see the exact name.\n\nDeferred tool catalog (call schemas via `tool_describe`, invoke via `tool_call`):\nbrowser tools (1):\n- browser_vault: Fill saved logins, 2FA codes, cards and addresses on the CURRENT browser page.\ncatalog tools (1):\n- manage_catalog: Find and install Hermes catalog plugins and hub skills for the user.\ncomputer_use tools (1):\n- computer_use: Drive the desktop via cua-driver: screenshots, mouse, keyboard, scroll, drag.\ncronjob tools (1):\n- cronjob_manage: Schedule recurring or one-off agent tasks (cron jobs): create, list, edit, run.\ndesktop_ui tools (10):\n- annotate_preview: Highlight preview-pane elements with lasting marks (drive_preview's fade).\n- close_terminal: Hide a background process's desktop terminal tab; the process keeps running.\n- desktop_preview: Open, close, or read the preview pane beside the chat.\n- drive_preview: Use the desktop preview-pane page: log in, fill forms, click through flows.\n- focus_pane: Show a desktop pane: chat, files, terminal, review (git diff) or sessions.\n- gui_tour: Run a guided desktop GUI tour: dim the screen, highlight elements, add popovers.\n- read_terminal: Read the in-app terminal pane beside this chat.\n- read_window_below: Identify the app window behind the Hermes desktop window (what the user is in).\n- set_theme: Change how the Hermes desktop app looks: accent colour, light/dark mode, layout.\n- show_tip: Point at one desktop UI element with a small arrow bubble (no dimming or tour).\nimage_gen tools (1):\n- image_generate: Generate or edit images (with reference images) using the configured model.\nproject tools (1):\n- desktop_project: Create or switch desktop Projects (named workspaces).\nsession_search tools (1):\n- session_search: Search or read past Hermes conversations (FTS5), or scroll inside one.\nterminal tools (1):\n- process_manage: Poll, wait on, send input to, or kill terminal(background=true) processes.\ntodo tools (1):\n- todo_list: Track a task list for multi-step work (3+ steps).",
+ "description": "Search 19 additional tools that are loaded on demand. Send one keyword query per capability you need; returns matching tool names and descriptions. Then `tool_describe` loads schemas and `tool_call` invokes. Tools already in your tool list need no search. Searches also cover the user's connected app accounts, whose tools are hosted and so never listed here (results named `connectors__<app>__<tool>`); `manage_connections` checks or connects an account.\n\nEvery tool listed below exists: never call it unavailable, and go straight to `tool_describe` when you see the exact name.\n\nDeferred tool catalog (call schemas via `tool_describe`, invoke via `tool_call`):\n- browser_vault: Fill saved logins, 2FA codes, cards and addresses on the CURRENT browser page.\n- manage_catalog: Find and install Hermes catalog plugins and hub skills for the user.\n- computer_use: Drive the desktop via cua-driver: screenshots, mouse, keyboard, scroll, drag.\n- cronjob_manage: Schedule recurring or one-off agent tasks (cron jobs): create, list, edit, run.\n- image_generate: Generate or edit images (with reference images) using the configured model.\n- desktop_project: Create or switch desktop Projects (named workspaces).\n- session_search: Search or read past Hermes conversations (FTS5), or scroll inside one.\n- process_manage: Poll, wait on, send input to, or kill terminal(background=true) processes.\n- todo_list: Track a task list for multi-step work (3+ steps).\ndesktop_ui tools (10):\n- annotate_preview: Highlight preview-pane elements with lasting marks (drive_preview's fade).\n- close_terminal: Hide a background process's desktop terminal tab; the process keeps running.\n- desktop_preview: Open, close, or read the preview pane beside the chat.\n- drive_preview: Use the desktop preview-pane page: log in, fill forms, click through flows.\n- focus_pane: Show a desktop pane: chat, files, terminal, review (git diff) or sessions.\n- gui_tour: Run a guided desktop GUI tour: dim the screen, highlight elements, add popovers.\n- read_terminal: Read the in-app terminal pane beside this chat.\n- read_window_below: Identify the app window behind the Hermes desktop window (what the user is in).\n- set_theme: Change how the Hermes desktop app looks: accent colour, light/dark mode, layout.\n- show_tip: Point at one desktop UI element with a small arrow bubble (no dimming or tour).",
"name": "tool_search",
"parameters": {
"properties": {
diff --git a/tests/fixtures/prompt_surface/tools/tool_search.json b/tests/fixtures/prompt_surface/tools/tool_search.json
index 78b66918e61..4bcbf1e4b3f 100644
--- a/tests/fixtures/prompt_surface/tools/tool_search.json
+++ b/tests/fixtures/prompt_surface/tools/tool_search.json
@@ -1,5 +1,5 @@
{
- "description": "Search 7 additional tools that are loaded on demand. Send one keyword query per capability you need; returns matching tool names and descriptions. Then `tool_describe` loads schemas and `tool_call` invokes. Tools already in your tool list need no search. `connectors__` names are tools of the user's app accounts (Gmail, Linear, ...); `manage_connections` checks or authorizes an account.\n\nEvery tool listed below exists: never call it unavailable, and go straight to `tool_describe` when you see the exact name.\n\nDeferred tool catalog (call schemas via `tool_describe`, invoke via `tool_call`):\nbrowser tools (1):\n- browser_vault: Fill saved logins, 2FA codes, cards and addresses on the CURRENT browser page.\ncomputer_use tools (1):\n- computer_use: Drive the desktop via cua-driver: screenshots, mouse, keyboard, scroll, drag.\ncronjob tools (1):\n- cronjob_manage: Schedule recurring or one-off agent tasks (cron jobs): create, list, edit, run.\nimage_gen tools (1):\n- image_generate: Generate or edit images (with reference images) using the configured model.\nsession_search tools (1):\n- session_search: Search or read past Hermes conversations (FTS5), or scroll inside one.\nterminal tools (1):\n- process_manage: Poll, wait on, send input to, or kill terminal(background=true) processes.\ntodo tools (1):\n- todo_list: Track a task list for multi-step work (3+ steps).",
+ "description": "Search 7 additional tools that are loaded on demand. Send one keyword query per capability you need; returns matching tool names and descriptions. Then `tool_describe` loads schemas and `tool_call` invokes. Tools already in your tool list need no search. Searches also cover the user's connected app accounts, whose tools are hosted and so never listed here (results named `connectors__<app>__<tool>`); `manage_connections` checks or connects an account.\n\nEvery tool listed below exists: never call it unavailable, and go straight to `tool_describe` when you see the exact name.\n\nDeferred tool catalog (call schemas via `tool_describe`, invoke via `tool_call`):\n- browser_vault: Fill saved logins, 2FA codes, cards and addresses on the CURRENT browser page.\n- computer_use: Drive the desktop via cua-driver: screenshots, mouse, keyboard, scroll, drag.\n- cronjob_manage: Schedule recurring or one-off agent tasks (cron jobs): create, list, edit, run.\n- image_generate: Generate or edit images (with reference images) using the configured model.\n- session_search: Search or read past Hermes conversations (FTS5), or scroll inside one.\n- process_manage: Poll, wait on, send input to, or kill terminal(background=true) processes.\n- todo_list: Track a task list for multi-step work (3+ steps).",
"name": "tool_search",
"parameters": {
"properties": {
diff --git a/tests/tools/test_tool_search_listing_layout.py b/tests/tools/test_tool_search_listing_layout.py
new file mode 100644
index 00000000000..ef679edbb38
--- /dev/null
+++ b/tests/tools/test_tool_search_listing_layout.py
@@ -0,0 +1,60 @@
+"""Layout of the deferred-tool catalog embedded in the tool_search description."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def _td(name: str, description: str) -> dict[str, Any]:
+ return {"type": "function", "function": {
+ "name": name, "description": description,
+ "parameters": {"type": "object", "properties": {}}}}
+
+
+def _register(toolset: str, names_and_descs: list[tuple[str, str]]) -> list[dict[str, Any]]:
+ from tools.registry import registry
+
+ defs = []
+ for name, desc in names_and_descs:
+ registry.register(name=name, handler=lambda args, **kwargs: "{}", schema=_td(name, desc),
+ toolset=toolset)
+ defs.append(_td(name, desc))
+ return defs
+
+
+def test_collapsing_one_huge_server_leaves_the_others_their_descriptions():
+ """An 800-tool server collapses to one summary line; a small server that fits in full
+ keeps its one-line descriptions instead of dropping to bare names."""
+ from tools.tool_search_catalog import build_catalog_listing_with_form
+
+ defs = _register("mcp-layouthuge", [(f"layouthuge_op_{i:04d}", "Do a huge-server thing.")
+ for i in range(800)])
+ defs += _register("mcp-layoutsmall", [("layoutsmall_render", "Render the current scene to a file."),
+ ("layoutsmall_inspect", "Summarize the objects in the scene.")])
+
+ text, form = build_catalog_listing_with_form(defs, max_tokens=1000)
+
+ assert text is not None and form == "mixed"
+ assert "layouthuge (800 tools — names not listed" in text
+ assert "- layoutsmall_render: Render the current scene to a file." in text.splitlines()
+ assert "layouthuge_op_0000" not in text
+
+
+def test_single_tool_groups_render_without_a_count_heading():
+ """A one-tool group is its tool line alone, placed before the multi-tool groups so it cannot
+ read as a member of the group above it."""
+ from tools.tool_search_catalog import build_catalog_listing_with_form
+
+ defs = _register("mcp-layoutpair", [("layoutpair_b", "Second paired tool."),
+ ("layoutpair_a", "First paired tool.")])
+ defs += _register("mcp-layoutsolo", [("layoutsolo_only", "The only solo tool.")])
+
+ text, form = build_catalog_listing_with_form(defs, max_tokens=4000)
+
+ assert text is not None and form == "full"
+ assert text.splitlines()[1:] == [
+ "- layoutsolo_only: The only solo tool.",
+ "layoutpair tools (2):",
+ "- layoutpair_a: First paired tool.",
+ "- layoutpair_b: Second paired tool.",
+ ]
diff --git a/tools/tool_search.py b/tools/tool_search.py
index 90631843bcf..4657a8e44a9 100644
--- a/tools/tool_search.py
+++ b/tools/tool_search.py
@@ -230,8 +230,9 @@ def _bridge_schema(name: str, description: str, properties: dict[str, Any],
_CONNECTIONS_HINT = (
- " `connectors__` names are tools of the user's app accounts (Gmail, Linear, ...); "
- "`manage_connections` checks or authorizes an account.")
+ " Searches also cover the user's connected app accounts, whose tools are hosted and so "
+ "never listed here (results named `connectors__<app>__<tool>`); `manage_connections` checks "
+ "or connects an account.")
def _search_description(deferred_count: int, listing: Optional[str], listing_form: str,
diff --git a/tools/tool_search_catalog.py b/tools/tool_search_catalog.py
index 609463bea36..15d3b393012 100644
--- a/tools/tool_search_catalog.py
+++ b/tools/tool_search_catalog.py
@@ -288,18 +288,23 @@ def build_catalog_listing_with_form(
if mode == "summary":
return (f"{label} ({len(tools)} tools — names not listed; "
f"discover via `{TOOL_SEARCH_NAME}`)")
- lines = [f"{label} tools ({len(tools)}):"]
if mode == "full":
- lines.extend(f"- {name}: {desc}" if desc else f"- {name}" for name, desc in tools)
+ lines = [f"- {name}: {desc}" if desc else f"- {name}" for name, desc in tools]
else:
- lines.append(", ".join(name for name, _ in tools))
- return "\n".join(lines)
+ lines = [", ".join(name for name, _ in tools)] if len(tools) > 1 else [f"- {tools[0][0]}"]
+ # A one-tool group's "<label> tools (1):" heading says nothing its single line does not.
+ return "\n".join(lines if len(tools) == 1 else [f"{label} tools ({len(tools)}):", *lines])
header = ("Deferred tool catalog (call schemas via "
f"`{TOOL_DESCRIBE_NAME}`, invoke via `{TOOL_CALL_NAME}`):")
def assemble_if_fits(modes: dict[str, str]) -> Optional[str]:
- available_blocks = {label: render_group(label, modes[label]) for label in groups}
+ # Headless one-tool lines go first, straight under the catalog header: placed between
+ # groups they would read as members of the group above them.
+ singles = [render_group(label, modes[label]) for label in sorted(groups)
+ if len(groups[label]) == 1 and modes[label] != "summary"]
+ available_blocks = {label: render_group(label, modes[label]) for label in groups
+ if len(groups[label]) > 1 or modes[label] == "summary"}
unavailable_blocks = {
row["name"]: (
f"{row['name']} ({row['tool_count']} tools unavailable: {row['unavailable']})"
@@ -312,18 +317,20 @@ def build_catalog_listing_with_form(
available_blocks[label] if label in available_blocks else unavailable_blocks[label]
for label in sorted(available_blocks | unavailable_blocks)
]
- text = "\n".join([header] + blocks)
+ text = "\n".join([header] + singles + blocks)
return text if math.ceil(len(text) / CHARS_PER_TOKEN) <= max_tokens else None
for mode in ("full", "names"): # 1. everything full; 2. everything names-only
- modes = {lbl: mode for lbl in groups}
- text = assemble_if_fits(modes)
+ text = assemble_if_fits({lbl: mode for lbl in groups})
if text is not None:
return text, mode
- # 3. Collapse the LARGEST rendered groups first (deterministic: size then label).
+ # 3. Collapse the LARGEST rendered groups first (deterministic: size then label); the servers
+ # left uncollapsed get their full lines back when those fit, else names-only.
+ summarized: set[str] = set()
for lbl in sorted(groups, key=lambda lbl: (-len(render_group(lbl, "names")), lbl)):
- modes[lbl] = "summary"
- text = assemble_if_fits(modes)
- if text is not None:
- return text, "groups" if all(m == "summary" for m in modes.values()) else "mixed"
+ summarized.add(lbl)
+ for rest in ("full", "names"):
+ text = assemble_if_fits({g: "summary" if g in summarized else rest for g in groups})
+ if text is not None:
+ return text, "groups" if len(summarized) == len(groups) else "mixed"
return None, "none"