unique_web_search 2026.24.0.dev1__tar.gz → 2026.24.0.dev2__tar.gz

{unique_web_search-2026.24.0.dev1 → unique_web_search-2026.24.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-web-search
-Version: 2026.24.0.dev1
+Version: 2026.24.0.dev2
 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.24.0.dev7,<2026.24.0rc0
+Requires-Dist: unique-toolkit[monitoring]>=2026.24.0.dev10,<2026.24.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

{unique_web_search-2026.24.0.dev1 → unique_web_search-2026.24.0.dev2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_web_search"
-version = "2026.24.0.dev1"
+version = "2026.24.0.dev2"
 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.24.0.dev7,<2026.24.0rc0",
+    "unique-toolkit[monitoring]>=2026.24.0.dev10,<2026.24.0rc0",
     "azure-core>=1.36.0,<2",
     "google-cloud-aiplatform>=1.128.0,<2",
     "google-auth>=2.43.0,<3",

{unique_web_search-2026.24.0.dev1 → unique_web_search-2026.24.0.dev2}/src/unique_web_search/prompts.py

@@ -39,11 +39,28 @@ When multiple sources are available, prioritize:
 4. **Primary sources**: Original reports over summaries
 5. **Domain expertise**: Medical info from health institutions, financial from finance sources
 
-**When sources are insufficient**: Clearly state "Based on available search results..." and indicate limitations.
-
 **REMEMBER**: Source numbers reset with each new WebSearch. Only use numbers from the most recent tool response.
 """
 
+_TOOL_FORMAT_INFORMATION_SYNTHESIS_SECTION = """
+## Synthesizing WebSearch results
+
+After one or more WebSearch tool calls, **synthesize** findings in your answer. Do not only cite facts when a single source made the answer obvious.
+
+**Evidence ledger (per facet or sub-question):** Track each facet with a confidence label:
+
+- **Confirmed** — the exact fact is supported by cited tool content [sourceX].
+- **Partial** — only part of the facet is supported; say what is missing [sourceX].
+- **Not found** — no on-topic public evidence after reasonable search/refinement; state what you tried (no citation required for absence).
+- **Related** — tool content is adjacent but does not answer the exact ask; cite it [sourceX] and label it **related, not confirmed**.
+
+**Mandatory behaviors:**
+
+- **Always summarize partial findings** before saying something is unavailable. Never reply with only "I couldn't find X" if the tool returned related material—put related material in a **Related leads** (or equivalent) subsection with citations.
+- For multi-facet tasks (diligence, Source of Wealth, company profiles), use a structured answer: direct answer → evidence by facet → gaps and limitations → related leads → optional next steps.
+- Distinguish **Confirmed** from **Related** in prose—do not imply ownership, revenue, or UBO facts unless citations support them.
+""".strip()
+
 
 _TOOL_FORMAT_INFORMATION_V3_DOMAIN_DIVERSITY_SECTION = """
 ## Domain Diversity Requirement
@@ -61,4 +78,6 @@ DEFAULT_TOOL_FORMAT_INFORMATION_FOR_SYSTEM_PROMPT_V3 = (
     DEFAULT_TOOL_FORMAT_INFORMATION_FOR_SYSTEM_PROMPT.rstrip()
     + "\n\n"
     + _TOOL_FORMAT_INFORMATION_V3_DOMAIN_DIVERSITY_SECTION
+    + "\n\n"
+    + _TOOL_FORMAT_INFORMATION_SYNTHESIS_SECTION
 )

{unique_web_search-2026.24.0.dev1 → unique_web_search-2026.24.0.dev2}/src/unique_web_search/services/executors/v3/executor.py

@@ -58,11 +58,13 @@ class WebSearchV3Executor(BaseWebSearchExecutor[WebSearchV3ToolParameters]):
         p = self.tool_parameters
         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.objective)
+            return await self._run_search(
+                query=p.payload.query, objective=p.relevance_focus()
+            )
         if isinstance(p.payload, FetchUrlsPayload):
             await self._message_log_callback.log_progress("_Reading Web Pages_")
             return await self._run_fetch_urls(
-                urls=p.payload.urls, objective=p.objective
+                urls=p.payload.urls, objective=p.relevance_focus()
             )
 
         msg = "WebSearchV3ToolParameters requires exactly one of 'query' or 'urls'."

{unique_web_search-2026.24.0.dev1 → unique_web_search-2026.24.0.dev2}/src/unique_web_search/services/executors/v3/prompts/tool_description.j2

@@ -3,7 +3,11 @@ The WebSearch tool returns up-to-date information from the web. It exposes two c
 - **Search** (`command: "search"`) — runs the configured search engine and returns SERP rows (URL, domain, title, snippet). Gives a high-level read of what relevant pages contain without crawling them. Useful for **exploration** and quick lookups when a snippet is enough to answer.
 - **Fetch** (`command: "read_urls"`) — crawls one or more URLs and returns full-page text. Useful for **deep dives** when the task is complex and needs exact figures, quotes, regulatory text, or specs, and when the user provides a URL directly.
 
-Each call performs **one** operation. Drive multi-part tasks by chaining calls.
+Each call performs **one** operation. Drive multi-part tasks by chaining calls; use **parallel** `search` calls for independent facets (short `query` each, not one long query).
+
+**`phase`:** `exploratory` (map what exists) | `target` (precise facet in `gap`) | `redirect` (related context when the facet is not on the web). **`gap`:** one atomic facet per call.
+
+**Complex research:** build an evidence ledger as you go and **synthesize** in the final answer—do not stop at "not found" if results contain related context.
 
 ### Fields
 
@@ -11,4 +15,4 @@ Each call performs **one** operation. Drive multi-part tasks by chaining calls.
 
 Never invent URLs.
 
-For a deeper playbook on when to search vs fetch (snippet hedging, canonical-source topics, sub-question decomposition, URL-selection rules, anti-patterns), activate the `web-search-v3` skill before/while using this tool.
+For the full playbook (search vs fetch, diligence decomposition, partial evidence, synthesis, URL-selection, anti-patterns, SoW examples), activate the `web-search-v3` skill before/while using this tool.

unique_web_search-2026.24.0.dev2/src/unique_web_search/services/executors/v3/prompts/tool_description_for_system_prompt.j2

@@ -0,0 +1,78 @@
+Use `WebSearch` for up-to-date information from the web. It exposes two capabilities, picked per call via `command`. Each invocation performs **one** operation; complex user tasks are handled by **chaining** invocations — use **parallel** `search` calls when several facets are independent (one short `query` per call, not one long query).
+
+### `phase` — research phase (required on every call)
+
+Set **`phase`** on each WebSearch invocation (replaces the old `objective` field):
+
+- **`exploratory`** — sense what exists on the web and what is closest to the user's ask. Use broad, short mapping queries. Typical at the start of a complex task or when scoping an entity.
+- **`target`** — pursue one specific facet named in `payload.gap` with a precise, short `payload.query`. Use for verifiable facts (revenue, ownership, officers, filings).
+- **`redirect`** — last resort when the exact facet is not on the public web. Search for **related, attributable** context (sector, peers, parent company, adjacent news). Label results as related, not confirmed; never invent figures or ownership.
+
+**`payload.gap`** — one atomic facet per call (not the whole user question). **`payload.query`** — ~3–8 keywords only; decompose multi-facet asks into parallel `search` calls instead of one bloated query.
+
+#### `command: "search"` — search the web
+
+Runs the configured search engine and returns SERP rows (URL, domain, title, snippet). It is **fast** and gives a **high-level read** of what relevant pages contain without paying the cost of crawling them.
+
+Use it when:
+
+- You need to **discover sources**: you don't yet have URLs and need the engine to surface candidates for a topic.
+- The user's question can be answered from **snippets alone** — a definition, a status, a current value, a short factual lookup.
+- You're at the **start of a complex task** and need to map out what's out there before deciding which pages are worth a deeper read.
+- You want to **scope or sanity-check** a topic cheaply (does this entity / event / product even exist? how recent is the latest coverage?).
+- You need to **cover a new gap / sub-question** in a multi-step task — issue another search rather than blindly fetching.
+
+#### `command: "read_urls"` — fetch full page content
+
+Crawls one or more URLs and returns the full-page text. It is **slower** than search but gives the **complete content** of the chosen pages, not just a snippet.
+
+Use it when:
+
+- The user **pasted a URL** or asked you to read a specific page — go straight here, do not search first.
+- The task is **complex / in-depth** and needs more than a snippet: exact figures, full quotes, regulatory text, contract language, statute numbers, API specs, version numbers.
+- The previous search returned **paraphrased / hedged snippets** ("around", "approximately", "is expected to", "reportedly") for a question that needs precision.
+- The topic is **canonical-source-driven** — financial filings (10-K, 10-Q, earnings releases), regulator publications, official product docs, peer-reviewed papers, primary press releases — where the page itself is the source of truth.
+- You found a **highly relevant** SERP hit but the title/snippet alone doesn't support the claim you want to make.
+- The snippets from the previous "search" commands are relevant but do not fully answer the question or fill the gap and fetching the full page is necessary.
+
+**Current date:** {{ date_string }}
+
+### Balance exploration and exploitation
+
+- **Explore first.** Start with `command: "search"` to get a cheap, high-level read of candidate pages. Cover one `gap` per call.
+- **Refine, don't escalate prematurely.** If the first search did not fill the `gap`, issue another `command: "search"` with a refined query (different keywords, narrower entity, different timeframe) before reaching for `read_urls`.
+- **Exploit when snippets aren't enough.** Switch to `command: "read_urls"` when snippets paraphrase / hedge, or the task needs exact figures, quotes, regulatory text, specs, or canonical-source content. Pick **1-3 high-signal URLs** from the most recent SERP — complementary domains preferred.
+- **User-provided URLs go straight to fetch.** If the user pasted URL(s), the first call should be `command: "read_urls"`. Do not "search" for a URL the user already supplied.
+- **Latency is a fair trade.** `read_urls` takes longer than `search`. That latency is acceptable on complex queries where the user expects depth — give them the answer that's actually grounded. Don't fetch when a snippet already answers the question; don't refuse to fetch when the snippet doesn't.
+
+### WebSearch — Complex and diligence-style research
+
+Use this pattern when the user needs **multiple facts about an entity** (ownership, revenue, officers, filings, sanctions, geography, industry context)—including Source of Wealth / KYC-style profiles where not everything is on the public web.
+
+- **Before the first WebSearch call** (in your reasoning, not in tool args), decompose the task into **5–10 atomic gaps**—each gap is one verifiable facet (e.g. legal name and jurisdiction, revenue scale, ownership / UBO signals, key executives, recent filings, adverse media, industry peer context).
+- **Execute gradually:** one `command: "search"` (and `read_urls` when snippets are insufficient) **per gap**, in a deliberate order (identity → scale → ownership → corroboration). Use `phase: "exploratory"` to map, then `phase: "target"` per facet; use `phase: "redirect"` only when a target facet has no public evidence after refinement.
+- **After each tool round**, update a mental **evidence ledger** per facet: **Confirmed**, **Partial**, **Not found**, or **Related only**. Do not discard partial or adjacent SERP hits—they may matter in the final synthesis.
+
+### WebSearch — When public evidence is missing or indirect
+
+- **Do not stop** after one empty or weak SERP for a gap. Refine the query (keywords, entity disambiguation, registry/filing terms, language) before marking a gap **Not found**.
+- If the **exact** fact is not published on the open web, still surface **related, attributable context** from search results: sector, approximate scale, parent/subsidiary links, adjacent filings, news mentioning the person or company, comparable peers. Label these clearly as **related, not confirmed** for the original ask.
+- **Never invent** figures, ownership percentages, or ultimate-beneficial-owner claims. **Never** present related context as if it answered the exact question.
+
+### WebSearch — Synthesizing before you answer
+
+After WebSearch research (or when the user needs an interim summary), **synthesize**—do not dump raw tool output or answer only the facets that were easy to find.
+
+For **complex** tasks, structure the answer as:
+
+1. **Direct answer** — what you can support with citations.
+2. **Evidence by facet** — facet → finding → confidence (**Confirmed** / **Partial** / **Related**) → [sourceX].
+3. **Gaps and limitations** — what was not found on the public web and which searches you tried.
+4. **Related leads** — indirect but useful pointers for the user's underlying goal (all cited).
+5. **Suggested next steps** (optional)—e.g. corporate registry, paid databases, user-provided documents—only when appropriate.
+
+For **simple** lookups, a short cited answer is enough; do not force the full structure.
+
+For the deeper explore-then-exploit playbook (snippet hedging, decomposition, partial evidence, synthesis, URL-selection, anti-patterns, worked examples including Source of Wealth), activate the `web-search-v3` skill before/while using this tool.
+
+Tool arguments are defined by the tool schema; the live JSON schema comes from the tool definition.

{unique_web_search-2026.24.0.dev1 → unique_web_search-2026.24.0.dev2}/src/unique_web_search/services/executors/v3/schema.py

@@ -11,12 +11,29 @@ class Command(StrEnum):
     FETCH_URLS = "read_urls"
 
 
+class SearchPhase(StrEnum):
+    """How this WebSearch call fits in the research arc."""
+
+    EXPLORATORY = "exploratory"
+    TARGET = "target"
+    REDIRECT = "redirect"
+
+
 class SearchPayload(BaseModel):
     gap: str = Field(
-        description="A brief description of the gap that the query is meant to fill"
+        description=(
+            "One atomic facet this call addresses (e.g. '2023 revenue band for Company X in CH')—"
+            "not the whole user question. Pair with `phase`: exploratory scopes the topic; "
+            "target pursues this facet precisely; redirect seeks related context when the facet "
+            "is unlikely to be on the public web."
+        )
     )
     query: str = Field(
-        description="Search query for the configured search engine. Query must be fixed for the entire rounds."
+        description=(
+            "Short search-engine keyword line (~3–8 words, not a sentence). "
+            "Do not pack multiple facets into one query—issue parallel `search` calls with "
+            "one `gap` each instead. Do not paste the user question or `gap` text here."
+        )
     )
 
 
@@ -35,14 +52,31 @@ class WebSearchV3ToolParameters(BaseModel):
         description="The command to execute. Must be either 'search' or 'read_urls'."
     )
 
-    objective: str = Field(
-        description="One concise sentence: what this call is meant to accomplish."
+    phase: SearchPhase = Field(
+        description=(
+            "Research phase for this call. "
+            "`exploratory` — sense what exists on the web and what is closest to the user's ask "
+            "(broad, mapping queries). "
+            "`target` — pursue one specific facet in `payload.gap` with a precise, short `query`. "
+            "`redirect` — last resort when the exact facet is not on the public web; find related, "
+            "attributable context (sector, peers, parent entity, adjacent news)—not invented facts."
+        )
     )
 
     payload: SearchPayload | 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
+        if isinstance(self.payload, SearchPayload):
+            return f"[{phase_label}] {self.payload.gap}"
+        urls_preview = ", ".join(self.payload.urls[:3])
+        if len(self.payload.urls) > 3:
+            urls_preview += ", …"
+        return f"[{phase_label}] {urls_preview}"
+
     @classmethod
     def schema_hint(cls) -> str:
         """Return a markdown-bulleted hint mirroring the field descriptions of this model.
@@ -68,6 +102,9 @@ class WebSearchV3ToolParameters(BaseModel):
             if name == "command":
                 choices = " or ".join(f'`"{c.value}"`' for c in Command)
                 lines.append(f"- **`{name}`** — {choices}.")
+            elif name == "phase":
+                choices = " | ".join(f'`"{c.value}"`' for c in SearchPhase)
+                lines.append(f"- **`{name}`** — {choices}.")
             elif name == "payload":
                 continue
             else:

{unique_web_search-2026.24.0.dev1 → unique_web_search-2026.24.0.dev2}/src/unique_web_search/skills/web-search-v3.md

@@ -1,11 +1,10 @@
 ---
-name: web-search
+name: web-search-v3
 description: >-
   Use this skill when the WebSearch tool is being used and the task is
-  non-trivial. Explains how to balance the `search` capability (SERP
-  snippets, cheap exploration) against the `read_urls` capability
-  (full-page fetch, deeper but slower) based on snippet hedging,
-  canonical-source topics, and sub-question coverage.
+  non-trivial. Explains how to balance `search` vs `read_urls`, decompose
+  complex diligence tasks, handle partial or missing public evidence,
+  and synthesize findings before answering.
 ---
 
 # WebSearch — Explore → Exploit Playbook
@@ -42,15 +41,13 @@ flowchart TD
 ## Tool fields
 
 - **`command`** (string, per call) — `"search"` or `"read_urls"`.
-- **`objective`** (string, per call) — One concise sentence: what this call
-  is meant to accomplish.
+- **`phase`** (string, per call) — `exploratory` | `target` | `redirect` (see
+  system prompt). Replaces legacy `objective`.
 - **`payload`** (object, per call) — Shape depends on `command`:
   - For `"search"`:
-    - **`gap`** — A brief description of what this query is meant to fill
-      (the specific missing fact / facet / sub-question).
-    - **`query`** — One focused search query (3-8 keywords; query operators
-      allowed). For time-sensitive topics you may incorporate the current
-      year or month to improve recall.
+    - **`gap`** — One atomic, verifiable facet (not the whole user question).
+    - **`query`** — Short keyword line (~3-8 words). One facet per call—use
+      parallel `search` calls instead of one long query.
   - For `"read_urls"`:
     - **`urls`** — HTTP(S) URLs to crawl for full-page text. Use only URLs
       returned by a prior `search` call or pasted by the user — **never
@@ -72,9 +69,10 @@ Read the user task and silently classify it:
   - Composite reasoning that needs sub-answers chained together.
   - Vague / multi-faceted topics the user expects you to cover broadly.
 
-For complex tasks, decompose into 2-5 self-contained sub-questions and run
-**one `command: "search"` per sub-question** (and follow-up
-`command: "read_urls"` calls as needed). Each sub-question should:
+For complex tasks (including Source of Wealth / KYC-style profiles),
+decompose into **5–10 atomic gaps** (one verifiable facet each) and run
+**one `command: "search"` per gap** (and follow-up `command: "read_urls"`
+calls as needed). Each gap should:
 
 - Be answerable on its own by one focused search (and possibly one fetch
   follow-up).
@@ -100,10 +98,10 @@ user already supplied.
 ## Step 3 — Sufficiency check after every search
 
 Before deciding the next call, judge the snippets you just received against
-the current `objective` and `gap`:
+the current `phase`, `gap`, and `query`:
 
 - Do they contain the **specific** number, quote, date, or name the
-  `objective` requires? (Snippets often paraphrase or truncate.)
+  the `gap` requires? (Snippets often paraphrase or truncate.)
 - Are there **≥2 corroborating domains** for fact-style claims, when
   accuracy matters?
 - Is the **freshness** consistent with the question?
@@ -112,11 +110,16 @@ the current `objective` and `gap`:
 
 Decide:
 
-- **Snippets sufficient** + still uncovered sub-questions ⇒ next call is
-  another `command: "search"` for the next sub-question.
-- **Snippets sufficient** + all sub-questions covered (or task was simple)
-  ⇒ stop calling and answer.
+- **Snippets sufficient** + still uncovered gaps ⇒ next call is another
+  `command: "search"` for the next gap.
+- **Snippets sufficient** + all gaps covered (or task was simple) ⇒ stop
+  calling and go to Step 5 (synthesize), then answer.
 - **Snippets insufficient** ⇒ go to Step 4.
+- **Gap not filled but snippets are adjacent** (sector context, related
+  company, news mentioning the entity without the exact fact) ⇒ record the
+  facet as **Related** in your evidence ledger, refine once if worthwhile,
+  then continue with the next gap—do not treat "no exact hit" as "nothing
+  useful."
 
 ### Triggers that mean snippets are not sufficient
 
@@ -145,15 +148,14 @@ just to "be thorough" when a snippet already answers cleanly.
 Issue a follow-up call with:
 
 - `command: "read_urls"`.
-- An `objective` like "Read full article X to extract <missing detail> for
-  <sub-question Y>".
+- `phase: "target"` and a `gap` naming the missing detail you need from the page.
 - `payload.urls` set to a **small, high-signal** subset (typically 1-3
   URLs; pick complementary domains) of URLs from the `url` fields of the
   SERP JSON you already received.
 
 Once the page text comes back, do another sufficiency check. If the task is
-complex and more sub-questions remain, continue with the next
-`command: "search"`; otherwise, answer.
+complex and more gaps remain, continue with the next `command: "search"`;
+otherwise, go to Step 5.
 
 ### URL-selection rules
 
@@ -167,6 +169,29 @@ complex and more sub-questions remain, continue with the next
 - For canonical-source topics, prioritize the **issuer's own page** (the
   regulator, the company, the standards body) over secondary coverage.
 
+## Step 5 — Synthesize, then answer
+
+Merge your **evidence ledger** across all gaps before writing to the user.
+
+**Confidence labels:** **Confirmed** (cited exact fact), **Partial** (cited
+fragment), **Not found** (reasonable search/refinement tried), **Related**
+(cited but does not answer the exact ask—say so explicitly).
+
+**Answer structure for complex tasks:**
+
+1. Direct answer (what citations support).
+2. Evidence by facet (facet → finding → confidence → [sourceX]).
+3. Gaps and limitations (what public web did not reveal; what you tried).
+4. Related leads (indirect but useful, all cited).
+5. Suggested next steps (optional: registry, paid DB, user documents).
+
+**Partial / missing evidence:**
+
+- Never answer with only "I couldn't find X" when tool results contain
+  related material—surface **Related leads** with citations.
+- Never invent figures, ownership, or UBO claims.
+- For simple single-fact tasks, a short cited answer is enough.
+
 ## Anti-patterns (do not do these)
 
 - Packing several sub-questions into one bloated `query`. Split them across
@@ -180,6 +205,9 @@ complex and more sub-questions remain, continue with the next
   plan stable for the whole task.
 - Setting a `payload` shape that doesn't match `command` (e.g. `urls` under
   a `"search"` command, or `query` under a `"read_urls"` command).
+- Stopping research after one weak SERP on a diligence facet without
+  refinement or recording **Related** context.
+- Dumping raw tool output without synthesis on multi-facet tasks.
 
 ## Worked examples
 
@@ -190,7 +218,7 @@ User: "What is the current US Fed funds target rate?"
 ```json
 {
   "command": "search",
-  "objective": "Look up the current Fed funds target rate range.",
+  "phase": "target",
   "payload": {
     "gap": "Current Fed funds target rate range and effective date.",
     "query": "current Fed funds target rate"
@@ -209,7 +237,7 @@ User: "Read https://example.com/policy.pdf and summarize."
 ```json
 {
   "command": "read_urls",
-  "objective": "Read the user-provided policy document and summarize it.",
+  "phase": "target",
   "payload": {
     "urls": ["https://example.com/policy.pdf"]
   }
@@ -234,7 +262,7 @@ First call (cover sub-question 1):
 ```json
 {
   "command": "search",
-  "objective": "Cover sub-question 1: Stripe cross-border fees and pricing.",
+  "phase": "target",
   "payload": {
     "gap": "Stripe cross-border / international card transaction fee percentages.",
     "query": "Stripe cross-border international card transaction fees pricing"
@@ -250,7 +278,7 @@ giving exact percentages. Follow up:
 ```json
 {
   "command": "read_urls",
-  "objective": "Read Stripe's official pricing page to extract exact cross-border fee percentages.",
+  "phase": "target",
   "payload": {
     "urls": ["https://stripe.com/pricing"]
   }
@@ -259,3 +287,74 @@ giving exact percentages. Follow up:
 
 Then resume with the next sub-question (`command: "search"` for Adyen
 cross-border fees), and so on.
+
+### Complex — Source of Wealth / private company profile
+
+User: "I need a Source of Wealth picture for Acme Holding AG (Switzerland)—
+revenues, ownership, and who runs it. It's not a listed company."
+
+**Decomposed gaps (in reasoning):**
+
+1. Legal identity and jurisdiction (Acme Holding AG, CH)
+2. Revenue scale or turnover signals (public estimates, filings, press)
+3. Ownership structure / shareholders / UBO signals
+4. Key executives and board
+5. Recent registry or filing references (if any public)
+6. Adverse media or sanctions mentions
+7. Industry / peer context if direct financials are sparse
+
+**Call 1 — identity:**
+
+```json
+{
+  "command": "search",
+  "phase": "exploratory",
+  "payload": {
+    "gap": "Legal name, registered office, and jurisdiction for Acme Holding AG Switzerland.",
+    "query": "Acme Holding AG Switzerland company"
+  }
+}
+```
+
+**Call 2 — revenue (after identity gap partially filled):**
+
+```json
+{
+  "command": "search",
+  "phase": "target",
+  "payload": {
+    "gap": "Revenue scale or turnover band for Acme Holding AG (latest available).",
+    "query": "Acme Holding AG Umsatz revenue turnover"
+  }
+}
+```
+
+If snippets hedge or omit figures, follow with `read_urls` on the best SERP
+(registry excerpt, annual report PDF, credible press).
+
+**Call 3 — ownership:**
+
+```json
+{
+  "command": "search",
+  "phase": "target",
+  "payload": {
+    "gap": "Ownership structure or named shareholders for Acme Holding AG.",
+    "query": "Acme Holding AG shareholders ownership"
+  }
+}
+```
+
+Continue gaps 4–7 similarly. After each round, update the ledger
+(Confirmed / Partial / Not found / Related).
+
+**Final answer outline (Step 5):**
+
+- **Direct answer:** Summarize only **Confirmed** items with [sourceX].
+- **Evidence by facet:** Table or bullets per gap above.
+- **Gaps and limitations:** e.g. "No public UBO disclosure found after …
+  searches."
+- **Related leads:** e.g. parent group mentioned in press [source3]—labeled
+  **related, not confirmed** as UBO.
+- **Next steps (optional):** Swiss commercial register extract, user-provided
+  financials.

unique_web_search-2026.24.0.dev1/src/unique_web_search/services/executors/v3/prompts/tool_description_for_system_prompt.j2

@@ -1,40 +0,0 @@
-Use `WebSearch` for up-to-date information from the web. It exposes two capabilities, picked per call via `command`. Each invocation performs **one** operation; complex user tasks are handled by **chaining** invocations.
-
-#### `command: "search"` — search the web
-
-Runs the configured search engine and returns SERP rows (URL, domain, title, snippet). It is **fast** and gives a **high-level read** of what relevant pages contain without paying the cost of crawling them.
-
-Use it when:
-
-- You need to **discover sources**: you don't yet have URLs and need the engine to surface candidates for a topic.
-- The user's question can be answered from **snippets alone** — a definition, a status, a current value, a short factual lookup.
-- You're at the **start of a complex task** and need to map out what's out there before deciding which pages are worth a deeper read.
-- You want to **scope or sanity-check** a topic cheaply (does this entity / event / product even exist? how recent is the latest coverage?).
-- You need to **cover a new gap / sub-question** in a multi-step task — issue another search rather than blindly fetching.
-
-#### `command: "read_urls"` — fetch full page content
-
-Crawls one or more URLs and returns the full-page text. It is **slower** than search but gives the **complete content** of the chosen pages, not just a snippet.
-
-Use it when:
-
-- The user **pasted a URL** or asked you to read a specific page — go straight here, do not search first.
-- The task is **complex / in-depth** and needs more than a snippet: exact figures, full quotes, regulatory text, contract language, statute numbers, API specs, version numbers.
-- The previous search returned **paraphrased / hedged snippets** ("around", "approximately", "is expected to", "reportedly") for a question that needs precision.
-- The topic is **canonical-source-driven** — financial filings (10-K, 10-Q, earnings releases), regulator publications, official product docs, peer-reviewed papers, primary press releases — where the page itself is the source of truth.
-- You found a **highly relevant** SERP hit but the title/snippet alone doesn't support the claim you want to make.
-- The snippets from the previous "search" commands are relevant but do not fully answer the question or fill the gap and fetching the full page is necessary.
-
-**Current date:** {{ date_string }}
-
-### Balance exploration and exploitation
-
-- **Explore first.** Start with `command: "search"` to get a cheap, high-level read of candidate pages. Cover one `gap` per call.
-- **Refine, don't escalate prematurely.** If the first search did not fill the `gap`, issue another `command: "search"` with a refined query (different keywords, narrower entity, different timeframe) before reaching for `read_urls`.
-- **Exploit when snippets aren't enough.** Switch to `command: "read_urls"` when snippets paraphrase / hedge, or the task needs exact figures, quotes, regulatory text, specs, or canonical-source content. Pick **1-3 high-signal URLs** from the most recent SERP — complementary domains preferred.
-- **User-provided URLs go straight to fetch.** If the user pasted URL(s), the first call should be `command: "read_urls"`. Do not "search" for a URL the user already supplied.
-- **Latency is a fair trade.** `read_urls` takes longer than `search`. That latency is acceptable on complex queries where the user expects depth — give them the answer that's actually grounded. Don't fetch when a snippet already answers the question; don't refuse to fetch when the snippet doesn't.
-
-For the deeper explore-then-exploit playbook (snippet hedging triggers, canonical-source topics, sub-question decomposition, URL-selection rules, anti-patterns, worked examples), activate the `web-search-v3` skill before/while using this tool.
-
-Tool arguments are defined by the tool schema; the live JSON schema comes from the tool definition.