The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
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.jsonindex 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.jsonindex 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.jsonindex 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.pynew file mode 100644index 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.pyindex 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.pyindex 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 Nonefor 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"