people-search · diff
git:20261104.803d78d to git:20261105.e6ccce5
37 added, 46 removed. Audit A to A.
---
name: people-search
- description: Find, verify, and rank people through repeated candidate-search API calls. Use for requests with a target number of people, or requests to find as many as possible, build a complete list, find more candidates, or keep searching. Preserve all verified matches instead of silently returning a shortlist.
+ description: Find, verify, and rank people using professional profiles and public sources. Use for people-search requests, including numeric targets, additional candidates, or finding as many as possible. Reuse sufficient evidence, research material gaps, and keep inferred leads separate from verified matches.
---
# People Search
- Find as many distinct, qualified people as the request and budget allow. A useful first batch is progress, not completion. Never relax the user's requirements to increase the count.
-
- Apply this policy to exhaustive searches and numeric targets, not single-person lookups or requests for a few examples. Explicit user limits, cancellation, and stopping instructions take priority.
+ Find people who meet the user's requirements, with evidence that supports the recommendation. Adapt the search depth and approach to the request.
## Core principles
- **Broad discovery:** Cover complementary candidate pools with targeted searches, adjusting the strategy as gaps emerge.
- **Strict verification:** Count or present a candidate as a match only after verifying they meet the user's criteria.
- **Complete accounting:** Keep every candidate's outcome explicit and preserve the full qualified set through ranking and delivery.
- ## API selection
-
- Choose by evidence need, using only enabled tools and their current schemas. This is not a mandatory all-tools pipeline.
-
- | Evidence need | API | Best use |
- | --- | --- | --- |
- | Natural-language professional brief | `people_search_semantic` | Discover professional profile pages and source text by meaning. |
- | Exact current title, employer, profile-country or skill filters | `people_search_structured` | Expand a structured candidate pool; current-role filters must not become extra requirements for past-experience searches. |
- | Complementary profile discovery or identity lookup | `people_search` | Find source-backed professional profiles by identity, role, employer, education, skill or location. |
- | Cases, interviews, projects or other experience evidence | `web_search` | Find qualification evidence beyond profile records. |
- | Read known public source pages | `web_contents` or `web_scrape` | Read source text to verify claims; reuse sufficient text already returned. |
+ ## Understand the request and choose tools
- For submitted jobs, use `company_contact_get` for people searches and `web_contents_get` for `web_contents`. These reads are not new discovery calls; each explicit structured-search next-page request is.
+ Choose tools by evidence need rather than running every available tool:
- ## Set up the search run
+ | Need | Useful tools |
+ | --- | --- |
+ | Natural-language professional brief | `people_search_semantic` |
+ | Exact title, employer, profile-country, or skill filters | `people_search_structured` |
+ | Complementary profile discovery or identity lookup | `people_search` |
+ | Cases, interviews, projects, or other experience evidence | `web_search` |
+ | Additional text from known public pages | `web_contents` or `web_scrape` |
- - Count one candidate-search API request initiated by Okou, such as one `people_search` request, as **one discovery API call**. Provider-internal queries, search directions, steps, and results never count as additional discovery API calls.
- - Default discovery budget: **8 discovery API calls**, including failed attempts. Profile lookups, verification, and tool discovery are not discovery API calls. An explicit user search budget replaces this default.
- - Before stopping for low yield, complete **at least 3 successful discovery API calls with 3 meaningfully different request focuses**. User limits can end the run earlier.
- - Evaluate each API call after deduplication and qualification review of its entire returned candidate batch. Do not increment successful-call or zero-yield counters for individual internal queries or directions.
- - Choose distinct focuses for the initial API requests, such as role/title variants, different organizations, or relevant communities/sources. These requests can use the same tool. Cosmetic query rewrites are not different request focuses; broader discovery must not relax the criteria used to qualify a person.
- - Reuse the task's candidate pool, evidence, and previously delivered results. An explicit request to continue starts a new run with fresh run counters, but retains this pool for deduplication. Never silently restart a run to reset its budget, or reset an explicit task-wide budget.
- - When using Okou data tools, run `okou data tools` and `okou data describe <tool-name>` before using an unfamiliar tool. Use only supported parameters; do not invent pagination or exclusion fields.
+ Use enabled tools and their current schemas.
- ## Repeat: API call → deduplicate → verify → record → decide
+ ## Reuse evidence before researching further
- 1. Make a discovery API call with an unused request focus or meaningfully extend a productive one. Use supported pagination when available. If a call returns mostly repeats or irrelevant people, pivot rather than resubmitting essentially the same query.
- 2. Deduplicate across the API call's entire returned candidate batch and against the existing pool. Prefer canonical public profile URLs or stable person IDs; otherwise compare names, affiliations, and supporting evidence. Citation/result numbers are not cross-call person IDs. Do not merge people solely because their names match, or count one person again because their title changed.
- 3. Review newcomers and actionable pending candidates against every hard requirement. Classify each as qualified, rejected, or unresolved, and retain their evidence and rejection or uncertainty reasons in the pool. Count only distinct, evidence-supported matches; a returned profile is not automatically a qualified person. For a request for additional people, exclude previously delivered matches from the new results, not from the pool.
- 4. Update the run record after each discovery API call, before deciding whether to finish:
+ - Start with the source-linked facts and text already returned. When they sufficiently support a requirement for the right person and timeframe, use them directly.
+ - Focus follow-up research on material gaps: missing proof, ambiguous identity, conflicting sources, or insufficient freshness. Search for the specific missing fact rather than researching the whole biography again. If one page lacks evidence, consider another relevant source.
+ - Stop checking a fact once it is sufficiently supported, clearly contradicted, or the necessary evidence is unavailable from relevant sources. Avoid repeated searches merely for reassurance; keep remaining uncertainty explicit.
+ - Exclude clear mismatches early. Treat missing, stale, or conflicting evidence as unresolved rather than proof that someone is ineligible.
- `successful_api_calls | request_focus | new_qualified | total_candidates | total_qualified | empty_call_streak | discovery_api_calls / budget`
+ For example, reuse a source that explicitly describes someone leading a team's first implementation. A relevant job title alone may suggest that experience, but still leaves the ownership requirement unverified.
- - `new_qualified` counts people newly qualified after this API call, not raw profiles, repeats, or already qualified people.
- - If `new_qualified > 0`, reset `empty_call_streak` to **0** and continue unless a completion condition below applies.
- - If a successful, fully reviewed API call adds **0** qualified people, increment `empty_call_streak` and use a different request focus for the next API call.
- - Errors, incomplete responses, and unresolved candidates are **unknown yield, not zero yield**: reset `empty_call_streak` to **0** and resolve the uncertainty or try another request focus within budget.
+ ## Work efficiently
- ## Completion gate
+ - Prefer responses with useful profile fields and source text when supported. Assess candidates together against the same requirements, keeping each person's evidence distinct.
+ - Use supported batch reads or bounded parallel lookups when they reduce waiting. Reuse existing or in-flight checks where practical instead of fetching the same evidence twice.
- Finish only when one of these conditions applies:
+ ## Count candidate-discovery calls
- - **Target met:** the explicit numeric target has been reached with distinct, verified people. This can happen before three successful discovery API calls.
- - **Low yield:** at least three successful discovery API calls cover at least three different request focuses, and the last **two consecutive discovery API calls** each add zero qualified people. Those two calls must use different request focuses and have no actionable unresolved candidates. This is a practical stopping heuristic, not proof that everyone has been found.
- - **Budget reached:** the discovery API call budget or an explicit user time/cost limit has been reached. Do not make another discovery API call. Use the remaining permitted verification work to support the final results.
- - **Blocked or cancelled:** the user stops the search, or a concrete access/tool failure prevents useful continuation. Explain the blocker; do not label a failed search as exhausted.
+ - Count **one successfully completed API request to find additional people** as **one candidate-discovery call**. Classify by purpose, not tool name: a `web_search` for new candidate names counts; the same tool used to verify a known candidate does not.
+ - Exclude qualification or identity checks, profile lookups, evidence-page reads, tool discovery, and job status/result reads. Also exclude failed, errored, or incomplete attempts; accepted/running jobs count only when successfully completed.
+ - Count outer API requests, not provider-internal queries, search directions, steps, or individual results. A valid empty or all-duplicate discovery response still counts; each successful candidate-discovery next-page request counts once.
+ - Apply this definition to both the discovery budget and any reported discovery count or “search rounds.” Report failures and verification work separately when useful; never add them to the discovery total.
- Otherwise, make the next discovery API call. Do not substitute a final answer, a long progress report, or “Would you like me to keep searching?” for required continuation.
+ ## Adapt search depth and decide when to stop
- A high duplicate rate is a reason to **change the next API request's focus**, never a standalone reason to finish the entire task. Finding a plausible-looking shortlist is not a completion condition.
+ - **Adjust search effort:** For numeric or open-ended searches, use **eight successful candidate-discovery calls** as an adjustable default, **not a hard cap or minimum**. Freely increase or reduce this number based on task complexity, coverage, and the likely value of further search. Explicit user call, time, cost, and stopping limits take priority.
+ - **Expand useful coverage:** Explore complementary candidate pools across roles, organizations, communities, and sources. Pivot when results are mostly duplicates or irrelevant; cosmetic query rewrites do not broaden coverage.
+ - **Meet numeric targets:** Prioritize promising candidates and decisive checks. Stop expanding when enough distinct, evidence-supported people meet the current request. Previously delivered matches do not satisfy a request for additional people.
+ - **Judge open-ended completion:** Continue while meaningful expansions produce additional qualified people. Consider stopping when relevant channels are reasonably covered and further distinct searches add little; weigh actionable unresolved leads before concluding that useful options are exhausted. A duplicate-heavy batch alone is a reason to pivot, not stop.
+ - **Build on prior progress:** Reuse the candidate pool, supporting evidence, and unresolved gaps on continuation, and reassess how much further search is useful. Keep lightweight notes and count each person once across duplicate and parallel results.
- ## Final response
+ ## Present useful results
- - By default, return **every verified, deduplicated match for the current request**, with supporting sources, **sorted by descending relevance to the user's criteria and preferences**. Ranking determines order, not inclusion: do not silently return only the top 5, top 10, or a representative sample. Without an explicit user result limit, the returned count must equal the verified-match count for this request.
- - Limit the presented results only when the user explicitly requests a result limit; state how many additional verified matches are not shown and retain them in the pool. If the full list is too long for an inline response, provide it as a complete deliverable and clearly label any inline shortlist as a preview.
- - Report the distinct candidate total, qualified/rejected/unresolved counts, number returned, successful discovery API calls, total discovery API attempts, and actual stopping reason. State any numeric-target shortfall. Keep unresolved people separate from verified matches, and never describe a budget-limited or low-yield search as a complete census.
+ - Return all verified, deduplicated matches for the current request, ranked by relevance, unless the user sets a result limit. For long lists, provide a complete deliverable and label any inline shortlist as a preview.
+ - Prefer Markdown tables for presenting candidate lists.
+ - Share an early batch when useful without waiting for every uncertain lead. Continue the remaining work in the same run and reconcile the complete list at the end; correct earlier claims if later evidence changes them.
+ - Include supporting sources and briefly explain material gaps, target shortfalls, or stopping limits. Summarize coverage or counts when useful. Do not describe a budget-limited or low-yield search as exhaustive.