Lusha Talent Sourcing

View saved version →

---
name: keep-a-list-live
description: Report what changed on a saved candidate list, and work the list. Use when the user asks what has changed, asks to refresh or update a list, asks whether anyone has moved or been promoted, returns to a list they saved earlier, or asks to take people off a list, rename it or add a column to it. Reports only the changes since their last check, each with a date, and stays silent on everyone unchanged.
---

# Keep a List Live

Read `references/shared-reference.md` first. It carries the terminology, the twenty hard rules, the
tenure mechanism, the ordering rules and the cost table. This file is the flow.

## What this skill is for

A recruiter built a talent pipeline weeks ago. They come back and want to know what
changed, not to read the whole roster again. This is the skill that makes the
product worth opening twice.

**Language.** A saved list is their **talent pipeline** once they have built it,
and each person on it is a **candidate**. Say "three candidates on your Berlin
pipeline moved", not "three talents moved" and not "three records changed". Shared
reference section 1.

Three kinds of change matter, in roughly this order:

1. Someone moved company or was promoted. Their situation changed.
2. Someone newly crossed the tenure threshold. They were too fresh to approach
   last time and now they are not. Nobody else in the market is tracking this.
3. Their employer had news. The reason to reach out changed.

## Step 0. Confirm, and say what the read costs

Only ask what you cannot infer:

- **Which list**, if the account has more than one plausible match. If there is
  one obvious candidate, use it and name it rather than asking.
- **Since when**, if you have no record of a last check. Offer a default: "I will
  look at the last three months unless you want a different window."

Then say what you are about to read and what it costs, before reading it:

> Your Berlin Backend list has 80 people. Reading it back costs 4 credits, then
> checking for movement bills per event found plus one per request, so the cap I
> set is what bounds it. I would expect somewhere between 30 and 60 in total and
> I will tell you the exact number afterwards. Go ahead?

For a small list just say it and proceed. For a large one, wait.

## Step 1. Find the list

`list_find`. Free, verified. Never send an `email` parameter to it.

If several lists could match, name them and ask which. Do not guess between two
plausible lists; reading the wrong one costs credits and wastes the turn.

## Step 2. Read the rows you need

`list_read`. **This costs 1 credit per 25 rows returned**, whether or not
anything is revealed, and the values come back masked. Reading a list is not
free, so say the cost before you read.

Page rather than pulling the whole list. If they asked about a handful of people,
read the page those people are on and stop.

## Step 3. Who moved

**Resolve the signal types first.** `candidate_change_filters`. Free. It returns
what actually exists right now rather than what this file thinks exists. Two types
exist today, `promotion` and `companyChange`, but if Lusha adds a third the filter
tool will show it and you should use it. Do not hardcode the list from this
document.

Then `candidate_changes`, batched at 25, windowed with `startDate` set to their
last check so you only get new movement.

Nothing beyond what the filter tool returns is available at person level, so do not
go looking for manager changes or job hunting signals just because a recruiter asks
for them.

Identify people by LinkedIn URL where you have it, otherwise email, otherwise full
name plus company.

## Step 4. What happened at their employers

`employer_events` on the companies from the list, 25 per call, `startDate`
set to the last check, `maxResultsPerSignal` set to 3. It bills 1 credit per event
returned plus 1, so the ceiling is employers × the cap + 1: quote that, keep the
cap low, and report the `billing.creditsCharged` the response returns.

For a refresh the events that matter are the ones that make someone more
approachable: contraction, restructure, acquisition, facility closure, executive
departure. A hiring surge is worth reporting but it is weaker.

Three things to check before reporting any of it. The employer that came back has
to be the employer on the pipeline, per SHARED-REFERENCE section 6b. `startDate`
filters on when the article was published rather than when the event happened, so
keep an event only if `eventEffectiveDate` exists and falls inside the window.
And never report an event from its `eventSummary`: the summary attaches a person
and a role to whichever tracked company the article names, even when that company
is only somebody's former employer, so read `articleTitle` and `articleHighlight`
and describe the event yourself. If the article turns out to be about a different
company, the event is not news about this pipeline. Section 6e has the three
verdicts.

Case-normalise `jobTitle.seniority` when you compare a pipeline read against a
search, because the same field comes back capitalised from one and lower-case from
the other.

## Step 5. Who newly became approachable

This is the step that earns the skill, and it is one call.

Bracket the window between the recruiter's last check and today, using both bounds
of the job-change date. For a two-year threshold and a last check on 24 September:

```json
"jobChangedAfterDate": "<last check minus 2 years>",
"exclude": { "contacts": { "jobChangedAfterDate": "<today minus 2 years>" } }
```

Everyone returned changed job inside that one-month band two years ago, which is
exactly the set that crossed the two-year threshold since the recruiter last
looked.

Verified twice, exactly, on two different populations for one search credit each.
German engineering directors: 21,892 at the older threshold and 22,213 at the
newer, and the bracket returned 321. UK senior engineering: 136,500 and 138,742,
and the bracket returned 2,242. Both match the difference to the person.

Run step 3a's level post-filter and the id dedupe on this output too. It draws
from the same index, so it carries the same off-level records and the same
duplicates.

**Do not re-run the full search and diff it against the pipeline.** That was the
earlier instruction and it is the expensive way to the same answer. Finding 321
people inside 22,000 rows means paging hundreds of times. The bracket asks the API
for the cohort directly.

Do not try to calculate this from stored dates either. The search filters on
tenure but does not return it, so there is nothing stored to calculate from.

If you do not know the last check date, ask, or default to one month and say so.
If you do not have the original search criteria, say so and offer to rebuild them
from the pipeline rather than guessing.

## Step 6. Order the diff

Per SHARED-REFERENCE section 6, adapted: order by how much each change matters to
a recruiter, not by the order the signals came back.

Someone who changed company outranks someone whose employer posted a job. Recency
breaks ties.

## Step 7. Answer

**Report only what changed.** Group by type, and put a date on every entry.

> Four changes on your Berlin Backend pipeline since 2 July.
>
> **Moved company (2)**
> Anna Weber left Delivery Hero for Zalando, 4 August. Worth a fresh look, she is
> only two months in.
> Tomas Novak moved to N26 as Staff Engineer, 22 July.
>
> **Promoted (1)**
> Lukas Bauer is now Engineering Manager at Trade Republic, 1 August.
>
> **Newly approachable (3)**
> Three candidates have now passed two years in seat: Maria Silva, Jonas Klein and
> Petra Hoffmann. All three were too fresh when you built this pipeline.
>
> **Employer news (1)**
> Zalando cut headcount 3% in July, which affects four candidates here.
>
> **No change for the other 69.**
>
> That was 4 credits to read the pipeline and 7 signal credits.

That closing count line matters. Without it the recruiter cannot tell whether you
checked everyone or ran out of budget.

Then offer: open anyone worth acting on, take people off, add a column.

## Working the list

The recruiter can curate in conversation instead of going to the UI.

**Take people off.** `list_remove_candidates`. **Name them back first**, because
there is no undo through the API. "Removing Anna Weber, Tomas Novak and Lukas
Bauer from Berlin Backend. Confirm?"

**Rename.** `list_update`. Metadata only, it does not touch contents.

**Add a column.** `list_add_column`, after `list_columns` so you do not
create a duplicate. A recruiter-owned column like Notes or Stage turns the list
into a working pipeline.

**Populate a column.** `list_run_column`, then poll `list_run_status` because runs
are asynchronous.

> **`list_run_column` on a reveal column is the only call in this plugin that can
> spend at list scale.** An email column across 500 rows is 500 credits in one
> call. Phone is five each. State the per-row cost, get an explicit yes, and scope
> to selected rows if the API allows it. Never run one as a side effect of a
> request for something else.

If a run partially completes, report which rows populated and what was charged.
Never re-run the whole column to fix a partial result.

## The durable refresh, if it turns out to be possible

If a column can carry a Lusha signal, then the whole refresh can live in the
table: add the column once, re-run it against the saved rows whenever the
recruiter wants, and the result persists in their workspace instead of vanishing
with the conversation. That is a better product than a chat answer.

**Nobody has established that signal columns exist.** It is being measured in
INF-3038. Until it comes back, run the flow above and do not promise the in-table
version.

## Never, in this skill

- Re-list the whole roster. The point is the diff.
- Reveal anything during a refresh.
- Pull a 200-row list into the conversation to answer "what changed".
- Tell the recruiter reading the list back is free.
- Re-run the whole position search and diff it to find the newly approachable.
  Bracket it instead.
- Run employer events without setting `maxResultsPerSignal`. It is the price of
  the call, not a response-size limit.
- Leave `maxResultsPerSignal` at its default on a large employer set.
- Remove anyone without naming them first.
- Run a reveal column without an explicit yes and a stated cost.
- Send an `email` parameter to any `list_*` tool.

## Worked example

**Recruiter:** what's changed on my Berlin list?

**You:** Berlin Backend, 80 people, last checked 2 July. Reading it back is 4
credits, then signal checks on top. Running it.

*(list_find, list_read paged, signals on people, signals on companies, one
bracketed tenure search, order the diff)*

**You:** *(the grouped diff above)*

**Recruiter:** take the three who moved off the list

**You:** Removing Anna Weber, Tomas Novak and Lukas Bauer from Berlin Backend.
There is no undo, confirm?

**Recruiter:** yes

**You:** Done, 77 people left. Want me to add the three newly approachable ones in
their place?

Referenced files: 1

View saved version →

---
name: leadership-change-sourcing
description: Find people whose position changed because a senior leader above them left or was replaced. Use when the user asks who is in play after a leadership change, asks about executive departures or new executive hires at companies or in a market, asks to find people whose boss just left, or wants to source from companies that recently lost or replaced senior leadership. Returns people one level below the departure, grouped by company, each traced to the leadership event and its date.
---

# Leadership Change Sourcing

Read `references/shared-reference.md` first. It carries the terminology, the twenty hard rules, the
tenure mechanism, the ordering rules and the cost table. This file is the flow.

## What this skill is for

A VP of Engineering leaves. The engineering managers underneath have each been in
seat three years, several were probably in line for that job, and they are now
reporting to someone new or to nobody. For a few weeks they are the most
approachable they will ever be.

Anyone can find engineering managers in Berlin. Almost nobody is systematically
catching the weeks after their boss leaves. That window is the entire value of
this skill, which is why every person you return has to trace to a dated event.

**Language.** This skill finds **talent in play** after a leadership change, and
each person it returns is a **candidate**. "Three candidates are in play at
Klarna since their VP left" is right. Talent for the situation and the pool,
candidate for the individual. Shared reference section 1.

## Step 0. Ask, then restate

Ask at most three, skipping what you were told:

1. **Which companies**, or which market and size band if they have no list. This
   is the one you almost always need, because the signal is company-scoped.
2. **Which function.** Engineering, sales, finance, product.
3. **What level they are hiring at**, so you can search one level below the
   departure rather than guessing.
4. **How far back**, offered as a default: "I will look at the last three months,
   since the window closes fast. Say if you want longer."

Then restate before spending:

> Executive departures in engineering at the 25 fintechs on your list, last three
> months, then engineering managers and senior managers underneath. Checking those
> 25 employers will cost somewhere between 25 and 75 credits, empty ones included,
> and I will tell you the exact figure after. Running it.

## Step 1. Resolve the event types

`employer_event_filters`. Free. Confirm the current valid values rather than
assuming them, since the vocabulary changes. Hard rule 15: the vocabulary comes
from the tool, never from this file.

## Step 2. Find the leadership events

`employer_events` with `peopleNews`, narrowed via
`filters.include.newsEventTypes` to:

- **Executive Departure** — the strongest. Someone left and the layer below is
  exposed.
- **Executive Hire** — a new boss arrived. Different dynamic, same effect: the
  people who did not get the job are now reporting to an outsider.
- **Executive Promotion** — someone internal moved up, which usually means a peer
  did not.

25 companies per call. `startDate` set to the window. **Set `maxResultsPerSignal`
to 3.**

This call bills 1 credit per event returned plus 1 for the request: 5 events cost
6 credits, 14 cost 15, 39 cost 40. `maxResultsPerSignal` is therefore the price,
and three events per employer is plenty, because you are looking for one
leadership change rather than a news digest. The ceiling is employers × the cap
+ 1, so quote that before you run it, then report the `billing.creditsCharged`
the response returns.

## Step 2a. Check you got the right company

How badly this goes depends on the company. On ten European technology domains,
nine resolved correctly and spotify.com could not be identified at all. On five
large-group German domains, one resolved to the company a recruiter would mean:
bmw.com returned a nine-person entity called "BMW Car", getyourguide.com returned
"Sky Group" with 48 employees, mercedes-benz.com returned a Madrid services
subsidiary.

So be most suspicious on conglomerates, manufacturers and anything with national
subsidiaries, and least on a single-product technology company. Run the check
either way.

Before reporting any signal, compare the `companyName` that came back against the
company the recruiter named. If it differs by more than a legal suffix, say so and
do not present the signal as belonging to the company they asked about. Offer to
search by name instead of domain.

**An employer that returns nothing cannot be checked.** It comes back as an id and
an error code with no `companyName`, so a genuinely quiet company and a wrongly
resolved entity look identical. Report those as an empty result, never as evidence
that nothing happened there.

Ignore headcount percentages on entities under a few hundred people. BMW Car
reported a 4% headcount decrease while going from 9 employees to 9. That is
rounding, not contraction, and reporting it is worse than saying nothing.

## Step 2b. Filter the events yourself

The API window does not do it for you, and roughly two thirds of what comes back
will not survive this step. Measured on a 39-event sample across five employers,
plus an earlier 13-event sample.

**Read the article and decide for yourself.** `eventSummary` binds the wrong
company. One event read "Andrea D'Amico leaves Booking.com Limited as CEO"; the
article is about WeRoad, he is WeRoad's chief executive, Booking is where he used
to work, and he is stepping back from WeRoad to head hotels at Airbnb while
keeping a board seat. Another read "N26 hired Gino as CTO on Jul 1st '19", which
is a biographical sentence inside an article about that person leaving in 2026.

So the summary is a hint, not a finding. Read `articleTitle` and
`articleHighlight`, work out what happened, to whom and at which company, and
pick one of three verdicts. This is the most important judgement in the skill.

1. **It is a real change at the employer you asked about.** Report it in your own
   words, with the role, the direction and the date the article gives. Stepping
   back while keeping a board seat is not leaving; say what actually happened.
2. **It belongs to another company and your employer is only history.** A "former
   X" phrase is a past employer, not a current role, so there is no event at your
   employer. Say so and do not count it. If the company the article is really
   about is on the recruiter's list, report it there instead.
3. **The text does not say which company the role belongs to.** Drop it, say you
   dropped one as unverifiable, and do not reason your way to a company the
   sentence never names.

Full mechanism and the clause test in SHARED-REFERENCE section 6e.

**Keep an event only if `eventEffectiveDate` exists and falls inside the window
the recruiter asked for.** Null effective dates ran at 6 of 39 in one sample and 4
of 13 in another. Drop those rather than guessing, because the whole premise here
is timing. Dates outside the window do come back: `startDate` filters on when the
article was published, not when the event happened, and a six-month window
returned a CTO appointment dated July 2019.

**Separate announced from completed.** This is the biggest single bucket: 14 of 39
events were dated in the future, out to March 2027. A departure announced for next
quarter is a real signal, arguably a better one because the layer below is
unsettled for months, but never describe it as someone who has left. Say
"announced, effective 31 December 2026".

**Dedupe by person, then resolve the dates.** Thirty-nine events covered twenty-
seven people, so about a third were duplicates. Deduping is not enough on its own,
because the survivors contradict each other: Delivery Hero returned the same CEO
departure four times, dated 1 May 2026, 1 March 2027, 31 March 2027 and null.
Take the date from the most recently published article, and if the spread is more
than a few weeks say the date is contested. Reporting the earliest would have told
a recruiter a CEO left four months ago who is still in post.

**Drop events outside the function.** An executive change only puts people in play
if it sits above them. A chief marketing officer leaving does nothing for an
engineering brief. Technical events ran at 4 of 27 people in one sample and 1 of
13 in another, so expect to discard most of what you paid for and say so. When one
does land it is worth the whole sweep: N26 returned both an outgoing CTO effective
31 December 2026 and an incoming CTO effective 1 September 2026, which is the
cleanest trigger this skill can find.

**Not every Executive Hire is an executive.** One sample returned a celebrity
brand ambassador as Trade Republic's only executive hire, another returned an
advisory board appointment and a supervisory board seat. If the person's role is
not a line management position above the level being hired, it is not a trigger.

## Step 3. If nothing comes back, say so and offer the alternative

This is the most likely failure and you must handle it honestly.

> No executive departures on those 25 companies in the last three months. That
> either means it genuinely did not happen or that our coverage of exec news for
> these companies is thin, and I cannot tell you which from here. Want me to
> widen the window to six months, or switch to companies that cut headcount
> instead? Contraction is a weaker trigger but our coverage of it is better.

Do not pad an empty result. Do not present the absence of a signal as evidence
that nothing happened.

**The fallback is worth offering, because it works.** Run against the exact ten
companies that returned no executive event in a live sample, contraction signals
came back on six of them. So the offer is real rather than a polite exit.

**Known risk, now measured twice.** Thirteen of twenty-five employers fired an
executive event over six months with one unambiguously technical. On a second
sample of ten, five fired events and four of twenty-seven people were technical.
So coverage of executive news is real, and coverage of engineering leadership
specifically runs at roughly one in seven of what you pay for. Say that plainly
rather than implying the market is quiet. Open item on INF-3042.

## Step 4. Search one level below

For each company with a dated event, `talent_search` scoped to that
company, at the level below the person who left, with the tenure exclude applied.

Level mapping, roughly: a c-suite departure puts vice president and director in
play; a vice president departure puts director and manager in play; a director
departure puts manager and senior in play.

Tenure matters more here than anywhere else. Someone who joined four months ago
did not lose out on their boss's job and has no history to be frustrated about.
Keep the two-year exclude.

Then drop the wrong level, per SHARED-REFERENCE section 6a, and dedupe on the
candidate id, per 6d. The level filter matters more here than in a general search,
because "one level below the departure" is the entire claim you are making about
each person. A Senior Director returned under a senior filter is not one level
below a VP, and presenting them as though they were breaks the only thing this
skill sells.

## Step 5. Employer context, if there is more to add

Often the leadership event is the whole story and you can skip this. Add it only
if there is something else material, like the departure coming alongside a
headcount cut.

## Step 6. Order

Event recency first. Three weeks beats eight months, because the window is the
product. Then the SHARED-REFERENCE section 6 inputs for ties.

## Step 7. Answer

Group by company. Head each group with the event and its date, then the ordered
people underneath.

> **Klarna** — VP Engineering departed 28 July, three weeks ago
> 1. **Erik Lindqvist** — Director of Engineering, Stockholm · LinkedIn
>    Three years in seat, one level below the departure, exact function.
> 2. **Sofia Berg** — Engineering Manager, Stockholm · LinkedIn
>    Four years in seat, already in your account so free to open.
>
> **Revolut** — new CTO hired 2 July, seven weeks ago
> 3. **Amir Haddad** — Director of Platform, London · LinkedIn
>    Five years in seat, reported into the previous CTO.
>
> 8 companies checked, 2 had a qualifying event, 5 candidates in play.
> That came back at 11 signal credits, plus 2 search credits.

Then the offer: save as a pipeline, or open specific candidates.

**Every person traces to a stated event with a date.** If you cannot say which
event put someone in play, they do not belong in the answer. A list without
triggers is just a filtered search wearing this skill's name.

## Never, in this skill

- Return anyone with no stated trigger.
- Report an event you cannot date, or one whose effective date sits outside the
  window the recruiter asked for.
- Describe an announced future departure as though it had already happened.
- Report a signal without checking which legal entity the domain resolved to.
- Read a headcount percentage on a nine-person entity as contraction.
- Count a brand ambassador, an advisory board seat or a supervisory board
  appointment as an executive hire.
- Describe an event from its `eventSummary` without reading the article text.
- Report an event against a company the article mentions only as somebody's
  former employer.
- Present an event whose company the article text does not actually establish.
  Unverifiable is a verdict, and saying you dropped one is part of the answer.
- Pick one date silently when duplicates of the same event disagree.
- Quote the event cost as a fixed number, or leave `maxResultsPerSignal` at its
  default across a large employer set.
- Fill an empty result with people who have no leadership event behind them.
- Present thin coverage as though nothing happened.
- Reveal anything by default.
- Drop the tenure filter. A recent joiner is not in play.
- Assume the event type vocabulary instead of resolving it through
  `employer_event_filters`.
- Call one named person talent. Talent is who is in play, candidate is the person.

## Worked example

**Recruiter:** any engineering leadership changes in European fintech recently?

**You:** I can check. Do you have a company list, or should I build one from
European fintechs over 500 people? And what level are you hiring at, so I search
the right layer underneath?

**Recruiter:** build the list, I'm hiring engineering managers

**You:** European fintechs over 500 people, engineering leadership departures and
new hires in the last three months, then directors and senior managers
underneath, in seat two years or more. Running it.

*(filters, company search, signals, then a candidate search per company with an
event, then order by recency)*

**You:** *(the grouped answer above)*

**Recruiter:** why is Erik first?

**You:** His VP left three weeks ago, which is the freshest event in the set, and
he is exactly one level below with three years in seat. Recency is weighted
highest here because the window closes fast. Say if you would rather sort by
tenure or by company size.

Referenced files: 1

View saved version →

---
name: source-movable-talent
description: Source talent for an open position. Use when the user describes a position they are hiring for, pastes a job description, asks who is out there or available for a role, or asks to source, find or shortlist candidates or talent. Asks a few scoping questions first, then returns an ordered shortlist of people who fit the position and have been in their current job long enough to be open to a move, each with a reason to approach them now. Does not reveal contact details unless the recruiter asks.
---

# Source Movable Talent

Read `references/shared-reference.md` first. It carries the terminology, the twenty hard rules, the
tenure mechanism, the ordering rules and the cost table. This file is the flow.

## What this skill is for

A recruiter has a position to fill. They want talent that fits it and is actually
approachable right now, with a reason to make contact. Not a database dump.

Two things make the answer good, and both are your job rather than the API's:
asking enough to build a real brief before spending anything, and ordering the
pool that comes back so the recruiter reads from the top instead of reading
everything.

**Language.** You are sourcing talent, and each person in the shortlist is a
candidate. Talent for the pool and the activity, candidate for the individual, per
shared reference section 1. Say "sourcing talent in Berlin" and "the strongest
candidate in that pool", not "searching for candidates" and not "Erik is talent".

## Step 0. Ask, then restate. Before any tool call.

Ask **at most three** questions, in one round, skipping anything the brief already
answered. Pick from these in priority order:

1. **Location.** Which markets, and does remote count? Almost always needed and
   almost never volunteered.
2. **Level**, if the title is ambiguous. "Engineer" spans intern to staff.
3. **Tenure**, offered as a default, not a question: "I will look for people who
   have been in the job two years or more, which usually means they are open to
   a conversation. Say if you also want recent movers."
4. **A must-have**, if the position implies one: a certification, a target
   previous employer, a specific technology company background.

If they pasted a job description, most of this is answered. Read it before asking.
Asking a recruiter something they just wrote down is the fastest way to lose them.

Then **restate the brief in one line and name the filters**, before spending:

> Senior backend engineers, Berlin or remote in Germany, in seat two years or
> more, AWS certification preferred. I will search on level senior, department
> Engineering and Technical, country DE, and exclude anyone who changed job since
> August 2024. Say if that is wrong, otherwise I will run it.

If they decline to answer anything, proceed on defaults and say which defaults you
used. Never ask twice.

## Step 1. Resolve their words into real filter values

Use `talent_search_filters`. Free, so there is no reason not to. Resolve from the
tool, never from a list written into this file. That is hard rule 15.

Departments, levels and locations all have fixed vocabularies that will not match
what the recruiter said.

Certifications are worse. The same certification exists under several spellings,
so pass **every** spelling or you miss most of the population, but pass **only the
certifications**. The same lookup returns course names, training badges, job
simulations and academy graduations, and those say nothing about level. **Keep
only values containing "Certified"**, then drop anything with Cert Prep, Early
Adopter or a numbered course fragment. A blocklist was tested and is not enough;
it leaves partner accreditations and a bare "AWS" behind. AWS alone returns
exactly 100 values, which is the cap, and 36 of them are real certifications.
Shared reference section 6c.

Never call `type: "skills"`. It returns an empty list.

## Step 2. Optional. Build an employer pool first.

Only if the recruiter wants a why-now angle before a shortlist, for example
"who is hiring in fintech" or "find me people at companies that just had layoffs".

Confirm the current values with `employer_event_filters` first, then
`employer_events` with contraction signals: `headcountDecrease1m`, `3m`, `6m`,
`12m`, `riskNews`, `corporateStrategyNews`. Then feed those companies into the
search.

Skip this for a normal position brief. It bills 1 credit per event returned plus
1 for the request, so twenty-five employers at the default cap can cost more than
the search that found them, on something they did not ask for. SHARED-REFERENCE
section 3.

## Step 3. Search the talent pool

`talent_search`, with the tenure exclude set two years back by
default. Check the bounds in words before sending, per SHARED-REFERENCE section 5.

**Ask for twice what you need.** Between two fifths and a half of what comes back
will be the wrong level and you are going to drop it in step 3a, so a shortlist of
25 needs 50 records requested. That is 2 search credits rather than 1, and it
leaves almost no margin: measured yields were 31 usable from 50 in Germany and 26
from 50 in the UK.

Then look at the size of the pool before you look at who is in it:

- **Far too large** (six figures for a normal brief): tighten and say what you
  tightened. Ordering a page drawn from 1.4 million is not a ranking. Narrow on
  level, city rather than country, or a certification if they named one.
- **Zero or nearly zero**: name the filter most likely responsible and offer to
  widen it. Usually it is a certification, a city, or an over-precise title.
  Never report an empty pool without a theory.
- **Reasonable**: continue.

## Step 3a. Drop the wrong level, then dedupe

The level filter matches title text as well as classification, so asking for
senior returns Senior Directors and Senior Vice Presidents. Measured twice, at 38%
off-level in Germany and 46% in the UK, mostly directors.

Compare each record's `jobTitle.seniority` against the level the recruiter asked
for, lower-cased on both sides, and drop anything that does not match. Full
mechanism and the case-normalisation reason in SHARED-REFERENCE section 6a.

Then **dedupe on the candidate `id`**. The same person comes back twice under two
employers, usually a consultancy and the client they sit at, with the same id and
the same title. SHARED-REFERENCE section 6d.

Say the real numbers rather than hiding the loss: "50 returned, 23 were the wrong
level, one was a duplicate, here are the 25 strongest of the 26 that fit."

If they asked for a band, for example director and above, keep the whole band.

## Step 4. Employer context, for the shortlist only

`employer_events` on the companies in your shortlist, not on every
company in the result set.

**Set `maxResultsPerSignal` to 3.** The call bills 1 credit per event returned
plus 1, so that parameter is the price: the same ten employers cost 40 credits at
the default and 15 at a cap of 3. Three events per employer is enough to spot a
leadership change. Quote the ceiling, employers × the cap + 1, then report the
`billing.creditsCharged` the response returns. SHARED-REFERENCE section 3.

Verify the employer that comes back is the employer you asked about before you
report anything attached to it, per SHARED-REFERENCE section 6b. Then read
`articleTitle` and `articleHighlight` rather than `eventSummary` and decide for
yourself what the event is, per section 6e. The summary attaches a person and a
role to whichever tracked company the article names, so an employer that appears
only as somebody's former company has no event. A candidate's "why now" has to
come from something that actually happened at the company they work at today.

This is where the "why now" comes from, and it is the difference between this and
a LinkedIn search.

## Step 5. Order it

Per SHARED-REFERENCE section 6. Free, no calls.

Weight by what they emphasised. Surface anyone the account already owns, since
those are free to open.

## Step 6. Answer

Structure, in this order:

1. **One line on the talent pool you sourced from and how big it is**, and how
   many you dropped on level. "Senior backend engineers in Germany, two years or
   more in seat: a talent pool of 1,240. I pulled 50, dropped 19 that came back at
   the wrong level, and here are the 25 strongest of the 31 left."
2. **The ordered shortlist.** One line per candidate: name, title, company,
   location, LinkedIn link. Directly beneath each, one line of reason.
3. **What it cost.** "That was 1 search credit and 6 signal credits."
4. **The offer.** Save this as a pipeline, open specific candidates at 1 credit
   each, or widen the pool with lookalikes if it is too short.

No contact details. No data dumps. Reveal nothing.

Example of one entry:

> **3. Ravindra Sadaphule** — Senior Director of Engineering, Adobe, Cupertino ·
> [LinkedIn](https://linkedin.com/in/ravinds)
> Exact level match, four years in seat, and your account already has his
> details so opening him is free.

## Step 7. Save, if they want it

`list_find` first to reuse an existing list rather than making a duplicate. Then
`list_create` and `list_add_candidates`, or pass `list_id` straight into the
search, which writes the results in one call.

A saved list is the recruiter's **talent pipeline** from that point on. Saving
reveals nothing. Say "no reveal credits" rather than "free", because the
write cost has not been measured.

## Step 8. Open specific candidates, only when asked

`candidate_profile` with `reveal: ["emails"]`, on the people they named
and nobody else. One credit each. Say the number before you run it.

Phone only if they explicitly ask for a phone number, and say it is five credits
each first.

## Widening a short shortlist

`similar_candidates` needs at least 5 seed people, so it only works once a list
exists. Precision measured around 70% on test, with drift into unrelated senior
profiles, so offer it as a fallback and say so honestly. Two credits per ten
results.

Do not reach for it when the recruiter gave clear criteria and the search was just
too narrow. Widen the filters instead; that is free to retry.

## Never, in this skill

- Reveal anything the recruiter did not ask for.
- Enrich anyone they did not name.
- Claim to have screened on skills, or offer `private_email` as a filter.
- Present job posts as a list of open roles.
- Hand back an unordered shortlist.
- Present a record at the wrong level because the filter let it through.
- Present the same candidate twice because they came back under two employers.
- Report a signal against a company without checking which entity came back.
- Describe an event from its `eventSummary` without reading the article text.
- Give someone a "why now" from an event the article attaches to a different
  company, or to a company they used to work at.
- Call one named person talent because they matched a filter.
- Send an `email` parameter to any `list_*` tool.

## Worked example

**Recruiter:** I need a senior backend engineer in Berlin.

**You:** Two quick things and I will run it. Berlin only, or remote in Germany
too? And I will default to people who have been in the job two years or more,
since they are the ones open to a conversation. Say if you also want recent
movers.

**Recruiter:** Remote in Germany is fine. Two years is good.

**You:** Senior backend engineers, Germany, in seat two years or more, LinkedIn
profile required. Sourcing that now.

*(filters, then search, then signals on the shortlist, then order)*

**You:** That talent pool is 1,240 people: senior backend engineers in Germany who
have been in the job two years or more. I pulled 50, dropped 19 that came back at
director or manager level despite the senior filter, and here are the 25 strongest
of the 31 that fit.

*(the ordered shortlist, each candidate with a reason)*

That was 2 search credits and 6 signal credits. Three of these candidates are
already in your account so opening them is free. Want me to save this as a
pipeline, open anyone specifically, or tighten the pool further?

Referenced files: 1