ha-mcp-dev 8.6.0.dev2981__tar.gz → 8.6.0.dev2987__tar.gz

{ha_mcp_dev-8.6.0.dev2981 → ha_mcp_dev-8.6.0.dev2987}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.6.0.dev2981
+Version: 8.6.0.dev2987
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Keywords: mcp,home-assistant,ai,automation,smart-home
 Author: Julien
@@ -413,7 +413,7 @@ Set ENABLE_TOOL_SEARCH=true (or toggle the option in the HA app). The full catal
 
 | Tool | Purpose |
 |------|---------|
-| `ha_search_tools` | BM25 English-keyword search across all tools, pinned ones included. Hidden tools return name, description, parameters, and annotations (`readOnlyHint` / `destructiveHint`) so the agent can pick the right one; a pinned tool returns a name-only stub (`pinned: true`) pointing back at the tool list, and does not use up a result slot. |
+| `ha_search_tools` | BM25 English-keyword search across all tools, pinned ones included. A hidden tool comes back compact: name, one-line description (the docstring's first paragraph), a one-line `params` list (types, enum values, required) and the proxy that executes it. `ha_search_tools(tools=[...])` returns the full definition (description, input schema and annotations) of the named tools, the second hop before a call. A pinned tool returns a name-only stub (`pinned: true`) pointing back at the tool list, and does not use up a result slot. |
 | `ha_call_read_tool` | Execute a `readOnlyHint` tool by name. Safe — clients can auto-approve. |
 | `ha_call_write_tool` | Execute a write tool that creates or updates data. |
 | `ha_call_delete_tool` | Execute a tool that removes / deletes data. |

{ha_mcp_dev-8.6.0.dev2981 → ha_mcp_dev-8.6.0.dev2987}/README.md

@@ -353,7 +353,7 @@ Set ENABLE_TOOL_SEARCH=true (or toggle the option in the HA app). The full catal
 
 | Tool | Purpose |
 |------|---------|
-| `ha_search_tools` | BM25 English-keyword search across all tools, pinned ones included. Hidden tools return name, description, parameters, and annotations (`readOnlyHint` / `destructiveHint`) so the agent can pick the right one; a pinned tool returns a name-only stub (`pinned: true`) pointing back at the tool list, and does not use up a result slot. |
+| `ha_search_tools` | BM25 English-keyword search across all tools, pinned ones included. A hidden tool comes back compact: name, one-line description (the docstring's first paragraph), a one-line `params` list (types, enum values, required) and the proxy that executes it. `ha_search_tools(tools=[...])` returns the full definition (description, input schema and annotations) of the named tools, the second hop before a call. A pinned tool returns a name-only stub (`pinned: true`) pointing back at the tool list, and does not use up a result slot. |
 | `ha_call_read_tool` | Execute a `readOnlyHint` tool by name. Safe — clients can auto-approve. |
 | `ha_call_write_tool` | Execute a write tool that creates or updates data. |
 | `ha_call_delete_tool` | Execute a tool that removes / deletes data. |

{ha_mcp_dev-8.6.0.dev2981 → ha_mcp_dev-8.6.0.dev2987}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.6.0.dev2981"
+version = "8.6.0.dev2987"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.15"

{ha_mcp_dev-8.6.0.dev2981 → ha_mcp_dev-8.6.0.dev2987}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.6.0.dev2981"
+version = "8.6.0.dev2987"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's

{ha_mcp_dev-8.6.0.dev2981 → ha_mcp_dev-8.6.0.dev2987}/src/ha_mcp/llm_exposure.py

@@ -15,7 +15,8 @@ axis from the global enable/disable in the settings UI:
 For embedded servers with the Home Assistant LLM API enabled, the single
 source of truth travels **in-band**: :class:`LlmExposureMiddleware` stamps
 every ``tools/list`` entry with
-``_meta.ha_mcp = {"llm_api_exposed": bool, "pinned": bool, "policy": {...}}``
+``_meta.ha_mcp = {"llm_api_exposed": bool, "pinned": bool, "params": str,
+"policy": {...}}``
 so the component (one more loopback MCP client) filters on data that can never
 drift from the server's settings, with zero extra round-trips. The ``policy``
 block reports the serving server's gating state (#1990 — see META_POLICY_KEY). Stamping re-reads the
@@ -51,6 +52,10 @@ logger = logging.getLogger(__name__)
 META_NAMESPACE = "ha_mcp"
 META_EXPOSED_KEY = "llm_api_exposed"
 META_PINNED_KEY = "pinned"
+# The one-line parameter summary the component's search hits show (#2633).
+# Rendered here so the component, which cannot import this package, carries
+# no copy of the renderer.
+META_PARAMS_KEY = "params"
 
 # Serving-server policy/identity block stamped alongside the per-tool keys
 # (#1990). A client (or a debugging agent) reading tools/list can see the
@@ -267,6 +272,8 @@ class LlmExposureMiddleware(Middleware):
         call_next: CallNext[mt.ListToolsRequest, Sequence[Tool]],
     ) -> Sequence[Tool]:
         """Stamp ``_meta.ha_mcp`` on every tool in the list result."""
+        from .transforms.compact_params import compact_params
+
         tools = await call_next(context)
         overrides, pinned = self._current_settings()
         policy_block = self._policy_block()
@@ -279,6 +286,7 @@ class LlmExposureMiddleware(Middleware):
                 tool.name, tool.tags or set(), overrides
             )
             namespace[META_PINNED_KEY] = tool.name in pinned
+            namespace[META_PARAMS_KEY] = compact_params(tool.parameters)
             namespace[META_POLICY_KEY] = policy_block
             meta[META_NAMESPACE] = namespace
             stamped.append(tool.model_copy(update={"meta": meta}))

{ha_mcp_dev-8.6.0.dev2981 → ha_mcp_dev-8.6.0.dev2987}/src/ha_mcp/read_only.py

@@ -348,6 +348,17 @@ def read_only_visible(tool: Tool) -> bool:
 def _raise_read_only_error(
     name: str, *, blocked_operation: str | None = None, allowed: str | None = None
 ) -> NoReturn:
+    raise_tool_error(
+        read_only_error_response(
+            name, blocked_operation=blocked_operation, allowed=allowed
+        )
+    )
+
+
+def read_only_error_response(
+    name: str, *, blocked_operation: str | None = None, allowed: str | None = None
+) -> dict[str, Any]:
+    """The structured ``READ_ONLY_MODE`` error for a blocked call to *name*."""
     context: dict[str, Any] = {"tool_name": name, "read_only_mode": True}
     if blocked_operation is not None:
         context["blocked_operation"] = blocked_operation
@@ -364,17 +375,15 @@ def _raise_read_only_error(
             f"'{name}' is a write-capable tool, so the call was blocked — "
             f"no changes were made."
         )
-    raise_tool_error(
-        create_error_response(
-            ErrorCode.READ_ONLY_MODE,
-            message,
-            suggestions=[
-                "Continue with read-only tools — searching, getting, and "
-                + "listing data all remain available.",
-                read_only_remedy_hint(),
-            ],
-            context=context,
-        )
+    return create_error_response(
+        ErrorCode.READ_ONLY_MODE,
+        message,
+        suggestions=[
+            "Continue with read-only tools — searching, getting, and "
+            + "listing data all remain available.",
+            read_only_remedy_hint(),
+        ],
+        context=context,
     )
 
 

{ha_mcp_dev-8.6.0.dev2981 → ha_mcp_dev-8.6.0.dev2987}/src/ha_mcp/server_tool_text.py

@@ -9,9 +9,10 @@ from __future__ import annotations
 
 # Description for the unified search tool
 SEARCH_TOOL_DESCRIPTION = (
-    "Search ALL Home Assistant tools by ENGLISH keyword. Returns matching "
-    "tools with descriptions, parameters, and annotations "
-    "(read/write/delete). Categories: entities, states, automations, "
+    "Search ALL Home Assistant tools by ENGLISH keyword. Each hit is "
+    "compact: name, one-line description, a one-line params list (types, "
+    "enum values, required), and the proxy that executes it. Categories: "
+    "entities, states, automations, "
     "scripts, dashboards, helpers, HACS, calendar, zones, labels, groups, "
     "areas, floors, history, statistics, devices, integrations, services, "
     "backups, todo, camera, blueprints, system, and more.\n\n"
@@ -20,13 +21,17 @@ SEARCH_TOOL_DESCRIPTION = (
     "(pinned: true); use the schema you already have.\n\n"
     "WORKFLOW:\n"
     "1. ha_search_tools(query='...') \u2014 find tools (this tool)\n"
-    "2. Execute: call the tool DIRECTLY by name (preferred), or use "
+    "2. ha_search_tools(tools=['<name>']) \u2014 full description and input "
+    "schema of the tool(s) you will call. Do this BEFORE calling: the compact "
+    "hit omits usage guidance, nested fields, defaults and parameter "
+    "descriptions.\n"
+    "3. Execute: call the tool DIRECTLY by name (preferred), or use "
     "a proxy for permission gating:\n"
     "   - ha_call_read_tool \u2014 readOnlyHint tools (safe, no side effects)\n"
     "   - ha_call_write_tool \u2014 destructiveHint tools that create/update\n"
     "   - ha_call_delete_tool \u2014 destructiveHint tools that remove/delete\n"
-    "Once you know a tool name, call it directly \u2014 no need to search "
-    "again.\n\n"
+    "Once you hold a tool's full schema, call it directly \u2014 no need to "
+    "repeat the keyword search or the schema lookup.\n\n"
     "If using proxies, call with TWO top-level params:\n"
     '   ha_call_read_tool(name="ha_search", arguments={"query": "..."})\n'
     "   Do NOT nest name/arguments inside the arguments param.\n"
@@ -40,8 +45,9 @@ SEARCH_TOOL_DESCRIPTION = (
 TOOL_DISCOVERY_INSTRUCTIONS = (
     "\n\n## Tool Discovery\n"
     "Tools already in your tool list are callable directly — "
-    "do not search for them. Once you know any tool’s name, "
-    "call it directly; never search for the same tool twice.\n\n"
+    "do not search for them. Once you hold a tool’s full schema, "
+    "call it directly; repeat neither the keyword search nor the "
+    "schema lookup for the same tool.\n\n"
     "Most other tools are NOT listed directly — use "
     "ha_search_tools to find them.\n\n"
     "WORKFLOW:\n"
@@ -49,8 +55,10 @@ TOOL_DISCOVERY_INSTRUCTIONS = (
     "naming the operation (e.g. 'get entity state'). Translate "
     "other languages first; entity, area and device names keep "
     "their original spelling.\n"
-    "2. Results include name, description, parameters, and "
-    "annotations (readOnlyHint/destructiveHint). A tool already "
+    "2. Results are compact: name, one-line description, a one-line "
+    "params list and the proxy to use. Before calling, fetch the full "
+    "description and input schema with ha_search_tools(tools=['<name>']). "
+    "A tool already "
     "in your list comes back as a name-only stub (pinned: true) "
     "— use the schema you already have.\n"
     "3. Execute the discovered tool — two options:\n"

{ha_mcp_dev-8.6.0.dev2981 → ha_mcp_dev-8.6.0.dev2987}/src/ha_mcp/tools/tools_search.py

@@ -618,7 +618,9 @@ class SearchTools(ComponentSearchMixin, OverviewMixin, StateMixin):
             result["tool_discovery"] = {
                 "hint": (
                     "This server uses search-based tool discovery. "
-                    "Use ha_search_tools(query='...') to find tools, then "
+                    "Use ha_search_tools(query='...') to find tools, "
+                    "ha_search_tools(tools=['<name>']) for the full input "
+                    "schema of the one you will call, then "
                     "execute the discovered tool directly by name (preferred), "
                     "or via a proxy for permission gating: "
                     "ha_call_read_tool, ha_call_write_tool, or "

{ha_mcp_dev-8.6.0.dev2981 → ha_mcp_dev-8.6.0.dev2987}/src/ha_mcp/transforms/categorized_search.py

@@ -35,6 +35,7 @@ from ha_mcp._vendor.mcp.types import ToolAnnotations
 
 from ..errors import TOOL_ERROR_LOG_LEVEL, ErrorCode, create_error_response
 from ..renamed_tools import adapt_retired_arguments, current_tool_name
+from .compact_params import compact_params, summary
 from .write_tool_note import DESKTOP_APPROVAL_NOTE
 
 if TYPE_CHECKING:
@@ -100,6 +101,14 @@ SEARCH_QUERY_DESCRIPTION = (
     "entity, area and device names keep their original spelling."
 )
 
+SEARCH_TOOLS_DESCRIPTION = (
+    "Exact tool names to return in full (description, input schema, "
+    "annotations); pinned tools come back as their stub. 'query' is ignored "
+    "when this is given."
+)
+
+_TOOL_NOT_FOUND = "Search by English keywords to find the right tool name."
+
 # ``manage`` names one interface that intentionally combines several
 # operations (.gemini/styleguide.md, Tool Naming Convention). Such a tool is
 # categorised by its annotations like any other, but every call proxy can
@@ -472,9 +481,10 @@ class CategorizedSearchTransform(BM25SearchTransform):
     The unified ``ha_search_tools`` searches across ALL tools regardless of
     category, pinned ones included (issue #2576: a pinned tool vanishing
     from search reads as "no such capability" to a small model). Hidden
-    hits carry their full definition and annotations so the LLM can pick a
-    proxy; pinned hits are rendered as a name-only stub pointing back at the
-    tool list, and never consume one of the ``max_results`` slots.
+    hits are compact (description, one-line params, proxy hint), and
+    ``tools=[...]`` returns their full definitions. Pinned hits are rendered
+    as a name-only stub pointing back at the tool list, and never consume
+    one of the ``max_results`` slots.
     """
 
     def __init__(
@@ -573,15 +583,35 @@ class CategorizedSearchTransform(BM25SearchTransform):
         transform = self
 
         async def search_tools(
-            query: Annotated[str, SEARCH_QUERY_DESCRIPTION],
+            query: Annotated[str, SEARCH_QUERY_DESCRIPTION] = "",
+            tools: Annotated[list[str] | None, SEARCH_TOOLS_DESCRIPTION] = None,
             ctx: Context = None,  # type: ignore[assignment]
         ) -> list[dict[str, Any]]:
             """Search for tools using English keywords.
 
-            Returns matching tool definitions ranked by relevance,
-            in the same format as list_tools.
+            Returns compact matches ranked by relevance; pass ``tools`` to
+            get the full definitions of named tools.
             """
             catalog = await transform.get_tool_catalog(ctx)
+            if tools:
+                return await transform._render_full(catalog, tools, ctx)
+            if not query.strip():
+                raise ToolError(
+                    json.dumps(
+                        create_error_response(
+                            code=ErrorCode.VALIDATION_INVALID_PARAMETER,
+                            message=(
+                                "Pass 'query' (English keywords) or 'tools' "
+                                "(exact tool names)."
+                            ),
+                            suggestions=[
+                                "ha_search_tools(query='create helper') finds tools.",
+                                "ha_search_tools(tools=['<name>']) returns a tool's full schema.",
+                            ],
+                        )
+                    ),
+                    log_level=TOOL_ERROR_LOG_LEVEL,
+                )
             results = await transform._search(catalog, query)
             return await transform._render_results(results)
 
@@ -610,46 +640,128 @@ class CategorizedSearchTransform(BM25SearchTransform):
                 slots -= 1
         return results
 
-    async def _render_results(self, tools: Sequence[Tool]) -> list[dict[str, Any]]:
-        """Serialize search results with ``execute_via`` hints."""
+    def _execute_via_hint(self, tool: Tool) -> str:
+        """Call form(s) for *tool* through each proxy ``_advertised_routes`` lists."""
         proxy_map: dict[Capability, str] = {
             "read": self._call_read_name,
             "write": self._call_write_name,
             "delete": self._call_delete_name,
         }
-        results = []
-        for tool in tools:
-            if tool.name in self._always_visible:
-                # The client already holds this tool's full definition —
-                # repeating a 5-9KB schema here is what overflows small
-                # context windows (#2576).
-                results.append(
-                    {
-                        "name": tool.name,
-                        "pinned": True,
-                        "execute_via": (
-                            f"{tool.name} is already in your tool list — "
-                            "call it directly with the schema you have; "
-                            "no search or proxy needed."
-                        ),
-                    }
+        routes = _advertised_routes(tool.name, _categorize_tool(tool))
+        if len(routes) == 1:
+            return _execute_via(proxy_map[routes[0]], tool.name)
+        hint = "; ".join(
+            f"{route} actions: {_execute_via(proxy_map[route], tool.name)}"
+            for route in routes
+        )
+        return hint[:1].upper() + hint[1:]
+
+    @staticmethod
+    def _pinned_stub(tool: Tool) -> dict[str, Any]:
+        # The client already holds this tool's full definition — repeating a
+        # 5-9KB schema here is what overflows small context windows (#2576).
+        return {
+            "name": tool.name,
+            "pinned": True,
+            "execute_via": (
+                f"{tool.name} is already in your tool list — "
+                "call it directly with the schema you have; "
+                "no search or proxy needed."
+            ),
+        }
+
+    async def _render_results(self, tools: Sequence[Tool]) -> list[dict[str, Any]]:
+        """Serialize search hits as compact entries with ``execute_via`` hints."""
+        return [
+            self._pinned_stub(tool)
+            if tool.name in self._always_visible
+            else {
+                "name": tool.name,
+                "description": summary(tool.description),
+                "params": compact_params(tool.parameters),
+                "execute_via": self._execute_via_hint(tool),
+            }
+            for tool in tools
+        ]
+
+    async def _render_full(
+        self, catalog: Sequence[Tool], names: list[str], ctx: Context
+    ) -> list[dict[str, Any]]:
+        """Full definitions of *names* from *catalog*, in the order given.
+
+        A pinned name gets the stub, an unknown one a not-found entry — or,
+        for a write tool Read Only Mode hides, the READ_ONLY_MODE error the
+        call proxies give, so the model learns why rather than concluding
+        the capability does not exist. When no name resolves the whole call
+        is an error.
+        """
+        by_name = {tool.name: tool for tool in catalog}
+        hidden = await self._read_only_hidden(names, by_name, ctx)
+        results: list[dict[str, Any]] = []
+        found = 0
+        for name in names:
+            tool = by_name.get(name)
+            if tool is None:
+                error = (
+                    hidden[name]
+                    if name in hidden
+                    else create_error_response(
+                        code=ErrorCode.RESOURCE_NOT_FOUND,
+                        message=f"Tool '{name}' not found.",
+                        suggestions=[_TOOL_NOT_FOUND],
+                        context={"tool_name": name},
+                    )
                 )
+                results.append({"name": name, **error})
                 continue
-            data = tool.to_mcp_tool().model_dump(
-                mode="json", exclude_none=True, by_alias=True
-            )
-            routes = _advertised_routes(tool.name, _categorize_tool(tool))
-            if len(routes) == 1:
-                data["execute_via"] = _execute_via(proxy_map[routes[0]], tool.name)
+            found += 1
+            if tool.name in self._always_visible:
+                results.append(self._pinned_stub(tool))
+            else:
+                data = tool.to_mcp_tool().model_dump(
+                    mode="json", exclude_none=True, by_alias=True
+                )
+                data["execute_via"] = self._execute_via_hint(tool)
+                results.append(data)
+        if not found:
+            if len(results) == 1:
+                error = results[0]
+            elif all(name in hidden for name in names):
+                error = {**hidden[names[0]], "results": results}
             else:
-                hint = "; ".join(
-                    f"{route} actions: {_execute_via(proxy_map[route], tool.name)}"
-                    for route in routes
+                missing = [name for name in names if name not in hidden]
+                message = f"No tool is named {', '.join(missing)}."
+                if hidden:
+                    message += " Read Only Mode hides the others; see their entries in results."
+                error = create_error_response(
+                    code=ErrorCode.RESOURCE_NOT_FOUND,
+                    message=message,
+                    suggestions=[_TOOL_NOT_FOUND],
+                    context={"results": results},
                 )
-                data["execute_via"] = hint[:1].upper() + hint[1:]
-            results.append(data)
+            raise ToolError(json.dumps(error), log_level=TOOL_ERROR_LOG_LEVEL)
         return results
 
+    @staticmethod
+    async def _read_only_hidden(
+        names: list[str], visible: dict[str, Tool], ctx: Context
+    ) -> dict[str, dict[str, Any]]:
+        """READ_ONLY_MODE errors for the *names* Read Only Mode hides."""
+        if not _read_only_mode() or all(name in visible for name in names):
+            return {}
+        from ..read_only import read_only_error_response, read_only_visible
+
+        registered = {
+            tool.name: tool for tool in await ctx.fastmcp.local_provider._list_tools()
+        }
+        return {
+            name: read_only_error_response(name)
+            for name in names
+            if name not in visible
+            and name in registered
+            and not read_only_visible(registered[name])
+        }
+
     def _make_categorized_proxy(
         self,
         proxy_name: str,

ha_mcp_dev-8.6.0.dev2987/src/ha_mcp/transforms/compact_params.py

@@ -0,0 +1,87 @@
+"""One-line renderings of a tool for compact search hits (#2633).
+
+``compact_params`` names every parameter with its type on one line and
+``summary`` is a description's first paragraph. The search transform renders
+hits with them, and :class:`ha_mcp.llm_exposure.LlmExposureMiddleware` stamps
+``params`` into each tool's ``_meta.ha_mcp`` so the custom component, which
+cannot import this package, shows the same line in its own search hits.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def _literal_labels(branch: dict[str, Any]) -> list[str | None]:
+    """Labels of the ``enum``/``const`` values *branch* admits; ``None`` is
+    kept as-is for the caller's nullable check."""
+    values = [*(branch.get("enum") or [])]
+    if "const" in branch:
+        values.append(branch["const"])
+    return [v if isinstance(v, str) or v is None else json.dumps(v) for v in values]
+
+
+def _plain_type(branch: dict[str, Any], *, nested: bool) -> str:
+    """Label of a branch without literal values."""
+    kind = branch.get("type")
+    if kind == "array":
+        items = _param_type(branch.get("items"))
+        return f"({items})[]" if "|" in items else f"{items}[]"
+    if isinstance(kind, str) and kind:
+        return kind
+    if nested and (isinstance(kind, list) or "anyOf" in branch or "oneOf" in branch):
+        return _param_type(branch)
+    return "object" if {"$ref", "properties", "allOf"} & branch.keys() else "any"
+
+
+def _param_type(node: Any) -> str:
+    """Type label for one parameter: ``|`` joins union branches, enum and
+    const values are spelled out inline, ``?`` marks nullable, ``T[]`` an
+    array of ``T``."""
+    if not isinstance(node, dict):
+        return "any"
+    kind = node.get("type")
+    if isinstance(kind, list):
+        branches: list[Any] = [{**node, "type": k} for k in kind]
+    else:
+        branches = node.get("anyOf") or node.get("oneOf") or [node]
+    labels: dict[str, None] = {}
+    nullable = False
+    for branch in branches:
+        if not isinstance(branch, dict):
+            continue
+        if values := _literal_labels(branch):
+            nullable = nullable or None in values
+            labels.update(dict.fromkeys(v for v in values if v is not None))
+        elif branch.get("type") == "null":
+            nullable = True
+        else:
+            labels[_plain_type(branch, nested=branch is not node)] = None
+    if not labels:
+        return "null" if nullable else "any"
+    return "|".join(labels) + ("?" if nullable else "")
+
+
+def compact_params(schema: Any) -> str:
+    """One line naming every parameter with its type and required marker;
+    ``none`` for a tool without parameters."""
+    props = schema.get("properties") if isinstance(schema, dict) else None
+    if not isinstance(props, dict) or not props:
+        return "none"
+    required = schema.get("required")
+    required = set(required) if isinstance(required, list) else set()
+    return "; ".join(
+        f"{name} ({_param_type(field)}{', required' if name in required else ''})"
+        for name, field in props.items()
+    )
+
+
+def summary(description: str | None) -> str:
+    """The first paragraph of a tool description, on one line.
+
+    A docstring opens with its summary line; the paragraphs after it (and
+    the BM25 keyword list ``SearchKeywordsTransform`` appends) come back
+    with the full definition from ``tools=[...]``.
+    """
+    return " ".join((description or "").split("\n\n", 1)[0].split())