unique_web_search 2026.30.0.dev0__tar.gz → 2026.30.0.dev1__tar.gz

{unique_web_search-2026.30.0.dev0 → unique_web_search-2026.30.0.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-web-search
-Version: 2026.30.0.dev0
+Version: 2026.30.0.dev1
 Summary: 
 Author: Andreas Hauri, Gustav Hartz, Rami Azouz
 Author-email: Andreas Hauri <andreas@unique.ch>, Gustav Hartz <gustav.hartz.ext@unique.ch>, Rami Azouz <rami.ext@unique.ch>
@@ -17,7 +17,7 @@ Requires-Dist: tavily-python>=0.7.11,<1
 Requires-Dist: unidecode>=1.4.0,<2
 Requires-Dist: azure-ai-projects>=1.0.0,<2
 Requires-Dist: azure-identity>=1.25.0,<2
-Requires-Dist: unique-toolkit[monitoring]>=2026.30.0.dev0,<2026.30.0rc0
+Requires-Dist: unique-toolkit[monitoring]>=2026.30.0.dev10,<2026.30.0rc0
 Requires-Dist: azure-core>=1.36.0,<2
 Requires-Dist: google-cloud-aiplatform>=1.128.0,<2
 Requires-Dist: google-auth>=2.43.0,<3
@@ -27,8 +27,8 @@ Requires-Dist: httpx>=0.28.1
 Requires-Dist: certifi>=2025.11.12
 Requires-Dist: jinja2>=3.1.6
 Requires-Dist: playwright>=1.58.0
-Requires-Dist: unique-search-proxy-core>=2026.30.0.dev0,<2026.30.0rc0
-Requires-Dist: unique-search-proxy-sdk>=2026.30.0.dev0,<2026.30.0rc0
+Requires-Dist: unique-search-proxy-core>=2026.30.0.dev2,<2026.30.0rc0
+Requires-Dist: unique-search-proxy-sdk>=2026.30.0.dev2,<2026.30.0rc0
 Requires-Python: >=3.12, <4.0
 Description-Content-Type: text/markdown
 

{unique_web_search-2026.30.0.dev0 → unique_web_search-2026.30.0.dev1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_web_search"
-version = "2026.30.0.dev0"
+version = "2026.30.0.dev1"
 description = ""
 readme = "README.md"
 requires-python = ">=3.12,<4.0"
@@ -23,7 +23,7 @@ dependencies = [
     "unidecode>=1.4.0,<2",
     "azure-ai-projects>=1.0.0,<2",
     "azure-identity>=1.25.0,<2",
-    "unique-toolkit[monitoring]>=2026.30.0.dev0,<2026.30.0rc0",
+    "unique-toolkit[monitoring]>=2026.30.0.dev10,<2026.30.0rc0",
     "azure-core>=1.36.0,<2",
     "google-cloud-aiplatform>=1.128.0,<2",
     "google-auth>=2.43.0,<3",
@@ -33,8 +33,8 @@ dependencies = [
     "certifi>=2025.11.12",
     "jinja2>=3.1.6",
     "playwright>=1.58.0",
-    "unique-search-proxy-core>=2026.30.0.dev0,<2026.30.0rc0",
-    "unique-search-proxy-sdk>=2026.30.0.dev0,<2026.30.0rc0",
+    "unique-search-proxy-core>=2026.30.0.dev2,<2026.30.0rc0",
+    "unique-search-proxy-sdk>=2026.30.0.dev2,<2026.30.0rc0",
 ]
 
 [build-system]

{unique_web_search-2026.30.0.dev0 → unique_web_search-2026.30.0.dev1}/src/unique_web_search/service.py

@@ -5,6 +5,8 @@ from time import time
 
 from jinja2 import Template
 from typing_extensions import override
+from unique_search_proxy_core.param_policy.exposed_params import ExposedParams
+from unique_search_proxy_core.search_engines.base import BaseSearchEngineConfig
 from unique_toolkit._common.chunk_relevancy_sorter.service import ChunkRelevancySorter
 from unique_toolkit.agentic.evaluation.schemas import EvaluationMetricName
 from unique_toolkit.agentic.feature_flags.feature_flags import (
@@ -97,6 +99,7 @@ class WebSearchTool(Tool[WebSearchConfig]):
         )
         self.debug = self.config.debug
         self._display_name = kwargs.get("display_name", "Web Search")
+        self.exposed_params_cls = self._resolve_exposed_params_cls()
 
         def content_reducer(web_page_chunks: list[WebPageChunk]) -> list[WebPageChunk]:
 
@@ -111,6 +114,13 @@ class WebSearchTool(Tool[WebSearchConfig]):
 
         self.content_reducer = content_reducer
 
+    def _resolve_exposed_params_cls(self) -> type[ExposedParams] | None:
+        """Resolve the exposed-params model from the search-engine config, if any."""
+        cfg = self.config.search_engine_config
+        if isinstance(cfg, BaseSearchEngineConfig):
+            return cfg.exposed_params_model()
+        return None
+
     def _resolve_search_engine_mode(self) -> SearchEngineMode:
         """Derive the search-engine mode, respecting CustomAPI overrides."""
         cfg = self.search_engine_service.config
@@ -119,14 +129,16 @@ class WebSearchTool(Tool[WebSearchConfig]):
 
     @override
     def tool_description(self) -> LanguageModelToolDescription:
+        exposed = self.exposed_params_cls
         if self.config.web_search_mode_config.mode == WebSearchMode.V1:
-            self.tool_parameter_calls = WebSearchToolParameters.from_tool_parameter_query_description(
-                self.config.web_search_mode_config.tool_parameters_description.query_description,
-                self.config.web_search_mode_config.tool_parameters_description.date_restrict_description,
+            self.tool_parameter_calls = WebSearchToolParameters.with_exposed_params(
+                exposed
             )
         else:
             if self.config.web_search_mode_config.mode == WebSearchMode.V3:
-                self.tool_parameter_calls = WebSearchV3ToolParameters
+                self.tool_parameter_calls = (
+                    WebSearchV3ToolParameters.with_exposed_params(exposed)
+                )
             else:
                 engine_mode = self._resolve_search_engine_mode()
                 self.tool_parameter_calls = WebSearchPlan.with_search_engine_mode(
@@ -137,7 +149,7 @@ class WebSearchTool(Tool[WebSearchConfig]):
 
         if self.config.web_search_mode_config.mode == WebSearchMode.V3:
             tool_description = Template(tool_description).render(
-                tool_parameters_schema=WebSearchV3ToolParameters.schema_hint(),
+                tool_parameters_schema=WebSearchV3ToolParameters.schema_hint(exposed),
             )
 
         return LanguageModelToolDescription(
@@ -202,7 +214,7 @@ class WebSearchTool(Tool[WebSearchConfig]):
 
         screening_service = await self._get_argument_screening_service_if_ff_enabled()
 
-        parameters_dump = parameters.model_dump()
+        parameters_dump = parameters.model_dump(by_alias=True)
         debug_info = WebSearchDebugInfo(parameters=parameters_dump)
 
         web_search_message_logger = WebSearchMessageLogger(
@@ -333,6 +345,7 @@ class WebSearchTool(Tool[WebSearchConfig]):
                 callbacks=callbacks,
                 tool_call=tool_call,
                 tool_parameters=parameters,
+                exposed_params_cls=self.exposed_params_cls,
             )
         if isinstance(parameters, WebSearchPlan):
             assert search_config.mode == WebSearchMode.V2
@@ -343,6 +356,7 @@ class WebSearchTool(Tool[WebSearchConfig]):
                 tool_call=tool_call,
                 tool_parameters=parameters,
                 max_steps=search_config.max_steps,
+                exposed_params_cls=self.exposed_params_cls,
             )
         elif isinstance(parameters, WebSearchToolParameters):
             assert search_config.mode == WebSearchMode.V1
@@ -356,6 +370,7 @@ class WebSearchTool(Tool[WebSearchConfig]):
                 refine_query_language_model=search_config.refine_query_mode.language_model,
                 mode=search_config.refine_query_mode.mode,
                 max_queries=search_config.max_queries,
+                exposed_params_cls=self.exposed_params_cls,
             )
         else:
             raise ValueError(f"Invalid parameters: {parameters}")

{unique_web_search-2026.30.0.dev0 → unique_web_search-2026.30.0.dev1}/src/unique_web_search/services/executors/base_executor.py

@@ -4,6 +4,7 @@ from time import time
 from typing import Generic, TypeVar
 
 from pydantic import BaseModel
+from unique_search_proxy_core.param_policy.exposed_params import ExposedParams
 from unique_toolkit.agentic.tools.tool_progress_reporter import (
     ProgressState,
 )
@@ -39,6 +40,7 @@ class BaseWebSearchExecutor(ABC, Generic[T]):
         callbacks: ExecutorCallbacks,
         tool_call: LanguageModelFunction,
         tool_parameters: T,
+        exposed_params_cls: type[ExposedParams] | None = None,
     ):
         # Extract from service context
         self.search_service = services.search_engine_service
@@ -61,6 +63,7 @@ class BaseWebSearchExecutor(ABC, Generic[T]):
         # Store tool parameters
         self.tool_call = tool_call
         self.tool_parameters = tool_parameters
+        self.exposed_params_cls = exposed_params_cls
 
         # Initialize notification state
         self._notify_name = ""
@@ -78,6 +81,17 @@ class BaseWebSearchExecutor(ABC, Generic[T]):
 
         self.notify_callback = notify_callback
 
+    def _extract_search_params(self, source: BaseModel) -> ExposedParams | None:
+        """Validate ``source`` against the exposed-params class, dropping tool-only fields.
+
+        Returns ``None`` when no knobs are exposed for this deployment. Otherwise
+        re-validates the source dump through ``exposed_params_cls``
+        (``extra="ignore"``) so only admin-exposed engine knobs remain.
+        """
+        if self.exposed_params_cls is None:
+            return None
+        return self.exposed_params_cls.model_validate(source.model_dump(by_alias=True))
+
     @property
     def notify_name(self):
         return self._notify_name

{unique_web_search-2026.30.0.dev0 → unique_web_search-2026.30.0.dev1}/src/unique_web_search/services/executors/v1/__init__.py

@@ -1,17 +1,15 @@
 from unique_web_search.services.executors.v1.config import (
     QueryRefinementConfig,
     RefineQueryMode,
-    WebSearchToolParametersDescriptionConfig,
     WebSearchV1Config,
 )
-from unique_web_search.services.executors.v1.executor import (
-    WebSearchV1Executor,
-)
+from unique_web_search.services.executors.v1.executor import WebSearchV1Executor
+from unique_web_search.services.executors.v1.schema import WebSearchToolParameters
 
 __all__ = [
     "QueryRefinementConfig",
     "RefineQueryMode",
-    "WebSearchToolParametersDescriptionConfig",
     "WebSearchV1Config",
     "WebSearchV1Executor",
+    "WebSearchToolParameters",
 ]

{unique_web_search-2026.30.0.dev0 → unique_web_search-2026.30.0.dev1}/src/unique_web_search/services/executors/v1/config.py

@@ -15,7 +15,6 @@ from unique_web_search.services.executors.v1.prompts import (
     DEFAULT_TOOL_DESCRIPTION,
     DEFAULT_TOOL_DESCRIPTION_FOR_SYSTEM_PROMPT,
     REFINE_QUERY_SYSTEM_PROMPT,
-    RESTRICT_DATE_DESCRIPTION,
 )
 from unique_web_search.settings import env_settings
 
@@ -26,34 +25,6 @@ class RefineQueryMode(StrEnum):
     DEACTIVATED = "Deactivated"
 
 
-_DEFAULT_QUERY_DESCRIPTION = "The search query to issue to the web."
-
-
-class WebSearchToolParametersDescriptionConfig(BaseModel):
-    model_config = get_configuration_dict()
-
-    query_description: Annotated[
-        str,
-        RJSFMetaTag.StringWidget.textarea(
-            rows=len(_DEFAULT_QUERY_DESCRIPTION.split("\n"))
-        ),
-    ] = Field(
-        default=_DEFAULT_QUERY_DESCRIPTION,
-        title="Query Parameter Description",
-        description="Advanced: Description of the search query parameter shown to the AI model.",
-    )
-    date_restrict_description: Annotated[
-        str,
-        RJSFMetaTag.StringWidget.textarea(
-            rows=len(RESTRICT_DATE_DESCRIPTION.split("\n"))
-        ),
-    ] = Field(
-        default=RESTRICT_DATE_DESCRIPTION,
-        title="Date Filter Description",
-        description="Advanced: Description of the date restriction parameter shown to the AI model.",
-    )
-
-
 class QueryRefinementConfig(BaseModel):
     model_config = get_configuration_dict()
 
@@ -101,12 +72,6 @@ class WebSearchV1Config(BaseWebSearchModeConfig[WebSearchMode.V1]):
         description="Maximum number of separate searches to run per user request. Only applies when Query Refinement is set to Advanced.",
     )
 
-    tool_parameters_description: WebSearchToolParametersDescriptionConfig = Field(
-        default_factory=WebSearchToolParametersDescriptionConfig,
-        title="Search Parameter Descriptions",
-        description="Advanced: Descriptions of each search parameter, shown to the AI model.",
-    )
-
     tool_description: Annotated[
         str,
         RJSFMetaTag.StringWidget.textarea(

{unique_web_search-2026.30.0.dev0 → unique_web_search-2026.30.0.dev1}/src/unique_web_search/services/executors/v1/executor.py

@@ -3,6 +3,7 @@ from time import time
 from typing import Literal, overload, override
 
 from pydantic import Field
+from unique_search_proxy_core.param_policy.exposed_params import ExposedParams
 from unique_toolkit import LanguageModelService
 from unique_toolkit._common.utils.structured_output.schema import StructuredOutputModel
 from unique_toolkit._common.validators import LMI
@@ -34,9 +35,6 @@ from unique_web_search.services.executors.v1.schema import WebSearchToolParamete
 from unique_web_search.services.search_engine.schema import (
     WebSearchResult,
 )
-from unique_web_search.utils import (
-    query_params_to_human_string,
-)
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -149,6 +147,7 @@ class WebSearchV1Executor(BaseWebSearchExecutor[WebSearchToolParameters]):
         refine_query_language_model: LMI,
         mode: RefineQueryMode = RefineQueryMode.BASIC,
         max_queries: int = 10,
+        exposed_params_cls: type[ExposedParams] | None = None,
     ):
         super().__init__(
             services=services,
@@ -156,6 +155,7 @@ class WebSearchV1Executor(BaseWebSearchExecutor[WebSearchToolParameters]):
             callbacks=callbacks,
             tool_call=tool_call,
             tool_parameters=tool_parameters,
+            exposed_params_cls=exposed_params_cls,
         )
         self.mode = mode
         self.refine_query_system_prompt = refine_query_system_prompt
@@ -164,10 +164,10 @@ class WebSearchV1Executor(BaseWebSearchExecutor[WebSearchToolParameters]):
 
     async def run(self) -> list[ContentChunk]:
         query = self.tool_parameters.query
-        date_restrict = self.tool_parameters.date_restrict
+        search_params = self._extract_search_params(self.tool_parameters)
 
         self.notify_name = "**Refining Query**"
-        self.notify_message = query_params_to_human_string(query, date_restrict)
+        self.notify_message = query
         await self.notify_callback()
 
         await self._message_log_callback.log_progress(
@@ -179,11 +179,7 @@ class WebSearchV1Executor(BaseWebSearchExecutor[WebSearchToolParameters]):
 
         web_search_results = []
 
-        queries_wo_results = [
-            query_params_to_human_string(refined_query, date_restrict)
-            for refined_query in elicitated_queries
-        ]
-        await self._message_log_callback.log_queries(queries_wo_results)
+        await self._message_log_callback.log_queries(elicitated_queries)
 
         for index, query in enumerate(elicitated_queries):
             if len(elicitated_queries) > 1:
@@ -193,11 +189,11 @@ class WebSearchV1Executor(BaseWebSearchExecutor[WebSearchToolParameters]):
             else:
                 self.notify_name = "**Searching Web**"
 
-            self.notify_message = query_params_to_human_string(query, date_restrict)
+            self.notify_message = query
             await self.notify_callback()
             await self._message_log_callback.log_progress(self.notify_message)
 
-            search_results = await self._search(query, date_restrict=date_restrict)
+            search_results = await self._search(query, params=search_params)
 
             await self._message_log_callback.log_web_search_results(search_results)
 
@@ -270,16 +266,16 @@ class WebSearchV1Executor(BaseWebSearchExecutor[WebSearchToolParameters]):
         return queries, refined_query.objective
 
     async def _search(
-        self, query: str, date_restrict: str | None
+        self,
+        query: str,
+        params: ExposedParams | None,
     ) -> list[WebSearchResult]:
         engine = self.search_service.config.engine.value
         start_time = time()
         _LOGGER.info(f"Company {self.company_id} Searching with {engine}")
         with metric_scope(search_duration, search_errors, engine=engine):
             search_total.labels(engine=engine).inc()
-            search_results = await self.search_service.search(
-                query, date_restrict=date_restrict
-            )
+            search_results = await self.search_service.search(query, params=params)
         end_time = time()
         delta_time = end_time - start_time
         _LOGGER.info(f"Searched with {engine} completed in {delta_time} seconds")
@@ -290,7 +286,11 @@ class WebSearchV1Executor(BaseWebSearchExecutor[WebSearchToolParameters]):
                 config=self.search_service.config.engine.name,
                 extra={
                     "query": query,
-                    "date_restrict": date_restrict,
+                    "params": (
+                        params.model_dump(by_alias=True, exclude_none=True)
+                        if params
+                        else None
+                    ),
                     "number_of_results": len(search_results),
                     "urls": [result.url for result in search_results],
                 },

{unique_web_search-2026.30.0.dev0 → unique_web_search-2026.30.0.dev1}/src/unique_web_search/services/executors/v1/prompts/__init__.py

@@ -11,6 +11,3 @@ DEFAULT_TOOL_DESCRIPTION_FOR_SYSTEM_PROMPT: str = load_template(
 REFINE_QUERY_SYSTEM_PROMPT: str = load_template(
     _PROMPTS_DIR, "refine_query_system_prompt.j2"
 )
-RESTRICT_DATE_DESCRIPTION: str = load_template(
-    _PROMPTS_DIR, "restrict_date_description.j2"
-)

unique_web_search-2026.30.0.dev1/src/unique_web_search/services/executors/v1/schema.py

@@ -0,0 +1,38 @@
+"""V1 WebSearch tool parameters (single-query tool call)."""
+
+from __future__ import annotations
+
+from pydantic import ConfigDict, Field, create_model
+from pydantic.alias_generators import to_camel
+from unique_search_proxy_core.param_policy.exposed_params import ExposedParams
+
+_DEFAULT_QUERY_DESCRIPTION = "The search query to issue to the web."
+
+
+class WebSearchToolParameters(ExposedParams):
+    """Parameters for the Websearch tool."""
+
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        extra="forbid",
+    )
+
+    query: str = Field(description=_DEFAULT_QUERY_DESCRIPTION)
+
+    @classmethod
+    def with_exposed_params(
+        cls,
+        exposed: type[ExposedParams] | None,
+    ) -> type[WebSearchToolParameters]:
+        """Graft admin-exposed engine knobs onto the V1 tool-parameter model.
+
+        Returns ``cls`` unchanged when nothing is exposed; otherwise builds a
+        dynamic subclass via ``create_model(__base__=(cls, exposed))``.
+        """
+        if exposed is None:
+            return cls
+        return create_model(
+            cls.__name__,
+            __base__=(cls, exposed),
+        )

{unique_web_search-2026.30.0.dev0 → unique_web_search-2026.30.0.dev1}/src/unique_web_search/services/executors/v2/executor.py

@@ -2,6 +2,7 @@ import asyncio
 import logging
 from time import time
 
+from unique_search_proxy_core.param_policy.exposed_params import ExposedParams
 from unique_toolkit.content import ContentChunk
 from unique_toolkit.language_model import LanguageModelFunction
 from unique_toolkit.monitoring import metric_scope
@@ -45,6 +46,7 @@ class WebSearchV2Executor(BaseWebSearchExecutor[WebSearchPlan]):
         tool_call: LanguageModelFunction,
         tool_parameters: WebSearchPlan,
         max_steps: int = 3,
+        exposed_params_cls: type[ExposedParams] | None = None,
     ):
         super().__init__(
             services=services,
@@ -52,6 +54,7 @@ class WebSearchV2Executor(BaseWebSearchExecutor[WebSearchPlan]):
             callbacks=callbacks,
             tool_call=tool_call,
             tool_parameters=tool_parameters,
+            exposed_params_cls=exposed_params_cls,
         )
 
         self.max_steps = max_steps

{unique_web_search-2026.30.0.dev0 → unique_web_search-2026.30.0.dev1}/src/unique_web_search/services/executors/v3/executor.py

@@ -7,6 +7,7 @@ import logging
 from time import time
 
 from unidecode import unidecode
+from unique_search_proxy_core.param_policy.exposed_params import ExposedParams
 from unique_toolkit.content import ContentChunk
 from unique_toolkit.language_model import LanguageModelFunction
 from unique_toolkit.monitoring import metric_scope
@@ -45,6 +46,7 @@ class WebSearchV3Executor(BaseWebSearchExecutor[WebSearchV3ToolParameters]):
         callbacks: ExecutorCallbacks,
         tool_call: LanguageModelFunction,
         tool_parameters: WebSearchV3ToolParameters,
+        exposed_params_cls: type[ExposedParams] | None = None,
     ):
         super().__init__(
             services=services,
@@ -52,6 +54,7 @@ class WebSearchV3Executor(BaseWebSearchExecutor[WebSearchV3ToolParameters]):
             callbacks=callbacks,
             tool_call=tool_call,
             tool_parameters=tool_parameters,
+            exposed_params_cls=exposed_params_cls,
         )
 
     async def run(self) -> list[ContentChunk]:
@@ -59,7 +62,9 @@ class WebSearchV3Executor(BaseWebSearchExecutor[WebSearchV3ToolParameters]):
         if isinstance(p.payload, SearchPayload):
             await self._message_log_callback.log_progress("_Executing Search_")
             return await self._run_search(
-                query=p.payload.query, objective=p.relevance_focus()
+                query=p.payload.query,
+                objective=p.relevance_focus(),
+                params=self._extract_search_params(p.payload),
             )
         if isinstance(p.payload, FetchUrlsPayload):
             await self._message_log_callback.log_progress("_Reading Web Pages_")
@@ -76,6 +81,7 @@ class WebSearchV3Executor(BaseWebSearchExecutor[WebSearchV3ToolParameters]):
         *,
         query: str,
         objective: str,
+        params: ExposedParams | None,
     ) -> list[ContentChunk]:
         self.notify_name = "**Searching Web**"
         self.notify_message = objective
@@ -102,7 +108,7 @@ class WebSearchV3Executor(BaseWebSearchExecutor[WebSearchV3ToolParameters]):
         await self._message_log_callback.log_queries([query])
         with metric_scope(search_duration, search_errors, engine=engine):
             search_total.labels(engine=engine).inc()
-            results = await self.search_service.search(query)
+            results = await self.search_service.search(query, params=params)
         await self._message_log_callback.log_web_search_results(results)
 
         delta_time = time() - time_start
@@ -113,6 +119,11 @@ class WebSearchV3Executor(BaseWebSearchExecutor[WebSearchV3ToolParameters]):
                 config=engine,
                 extra={
                     "query": query,
+                    "params": (
+                        params.model_dump(by_alias=True, exclude_none=True)
+                        if params
+                        else None
+                    ),
                     "number_of_results": len(results),
                     "urls": [result.url for result in results],
                 },

{unique_web_search-2026.30.0.dev0 → unique_web_search-2026.30.0.dev1}/src/unique_web_search/services/executors/v3/schema.py

@@ -1,9 +1,21 @@
 """V3 WebSearch tool parameters: a flat schema with exactly one of ``query`` or ``urls`` per call."""
 
+from __future__ import annotations
+
 import typing
 from enum import StrEnum
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, create_model
+from pydantic.alias_generators import to_camel
+from unique_search_proxy_core.param_policy.exposed_params import ExposedParams
+
+# Strict LLM-facing config: camelCase aliases + forbid extras, while still
+# inheriting ExposedParams.model_json_schema (strips title/default noise).
+_LLM_TOOL_MODEL_CONFIG = ConfigDict(
+    alias_generator=to_camel,
+    populate_by_name=True,
+    extra="forbid",
+)
 
 
 class Command(StrEnum):
@@ -19,7 +31,9 @@ class SearchPhase(StrEnum):
     REDIRECT = "redirect"
 
 
-class SearchPayload(BaseModel):
+class SearchPayload(ExposedParams):
+    model_config = _LLM_TOOL_MODEL_CONFIG
+
     gap: str = Field(
         description=(
             "One atomic facet this call addresses (e.g. '2023 revenue band for Company X in CH')—"
@@ -36,17 +50,32 @@ class SearchPayload(BaseModel):
         )
     )
 
+    @classmethod
+    def with_exposed_params(
+        cls,
+        exposed: type[ExposedParams] | None,
+    ) -> type[SearchPayload]:
+        """Graft admin-exposed engine knobs onto the search payload model."""
+        if exposed is None:
+            return cls
+        return create_model(
+            cls.__name__,
+            __base__=(cls, exposed),
+        )
+
 
 class FetchUrlsPayload(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
     urls: list[str] = Field(
         description="HTTP(S) URLs to crawl for full-page text. Use only URLs returned by a prior search or pasted by the user."
     )
 
 
-class WebSearchV3ToolParameters(BaseModel):
+class WebSearchV3ToolParameters(ExposedParams):
     """Root JSON for the V3 WebSearch tool: set exactly one of ``query`` or ``urls``."""
 
-    model_config = ConfigDict(extra="forbid")
+    model_config = _LLM_TOOL_MODEL_CONFIG
 
     command: Command = Field(
         description="The command to execute. Must be either 'search' or 'read_urls'."
@@ -67,6 +96,29 @@ class WebSearchV3ToolParameters(BaseModel):
         description="The payload of the command. Must be either a SearchPayload or a FetchUrlsPayload."
     )
 
+    @classmethod
+    def with_exposed_params(
+        cls,
+        exposed: type[ExposedParams] | None,
+    ) -> type[WebSearchV3ToolParameters]:
+        """Rebuild the payload union with an exposed ``SearchPayload`` subtype."""
+        search_payload = SearchPayload.with_exposed_params(exposed)
+        if search_payload is SearchPayload:
+            return cls
+        return create_model(
+            cls.__name__,
+            __base__=cls,
+            payload=(
+                search_payload | FetchUrlsPayload,
+                Field(
+                    description=(
+                        "The payload of the command. Must be either a SearchPayload "
+                        "or a FetchUrlsPayload."
+                    ),
+                ),
+            ),
+        )
+
     def relevance_focus(self) -> str:
         """Focus string for notify UI, snippet judging, and content processing."""
         phase_label = self.phase.value
@@ -78,23 +130,28 @@ class WebSearchV3ToolParameters(BaseModel):
         return f"[{phase_label}] {urls_preview}"
 
     @classmethod
-    def schema_hint(cls) -> str:
+    def schema_hint(
+        cls,
+        exposed: type[ExposedParams] | None = None,
+    ) -> str:
         """Return a markdown-bulleted hint mirroring the field descriptions of this model.
 
         Mirrors the legacy hand-written prompt block: one bullet per top-level
         field, with the ``payload`` bullet expanded into one inline JSON sketch
         per ``command`` value (since ``payload`` is a discriminated union).
         Field descriptions are inlined as ``<...>`` placeholders so the prompt
-        stays in sync with the Pydantic model.
+        stays in sync with the Pydantic model. Exposed knobs render under their
+        camelCase aliases.
         """
 
         def _inline_json(payload_model: type[BaseModel]) -> str:
             parts: list[str] = []
             for name, field in payload_model.model_fields.items():
-                placeholder = f"<{field.description or name}>"
+                key = field.alias or name
+                placeholder = f"<{field.description or key}>"
                 if typing.get_origin(field.annotation) is list:
                     placeholder = f"[{placeholder}]"
-                parts.append(f'"{name}": {placeholder}')
+                parts.append(f'"{key}": {placeholder}')
             return "{ " + ", ".join(parts) + " }"
 
         lines: list[str] = []
@@ -111,8 +168,9 @@ class WebSearchV3ToolParameters(BaseModel):
                 lines.append(f"- **`{name}`** — {field.description or name}")
 
         lines.append("- **`payload`** — Shape depends on `command`:")
+        search_payload = SearchPayload.with_exposed_params(exposed)
         for cmd, payload_model in (
-            (Command.SEARCH, SearchPayload),
+            (Command.SEARCH, search_payload),
             (Command.FETCH_URLS, FetchUrlsPayload),
         ):
             lines.append(f'  - For `"{cmd.value}"`: `{_inline_json(payload_model)}`.')