Vayora MCP tools for sourcing and contact lookups
Search beyond your own database, file the people worth keeping as candidates, and look up an email or mobile number. These are the tools that can spend your workspace's lookup allowance, so each one says what it costs.
Written by the Vayora team. Updated 29 October 2026.
The tools
5 tools: 2 read and 3 write. A read tool works on a connection made read-only. A write tool needs the person to have ticked Allow changes when they connected.
search_outside_bookSearch for people outside your database who match a title, place, skills, seniority or industry, or a saved role.
Takes: role_title, job_titles, locations, skills, seniority, industries, min_years, requisition_id, limit=10, cursor, relax (all optional)
Returns: People with work history and fit reasons, never an email or phone number, plus a cursor for the next page and a note on any filters that were relaxed.
Credits: Uses the monthly outside-search allowance, not enrichment credits
Read scope, but it holds search allowance and saves what it finds, so hosts are told it is not read-only. Recruiter or admin only.
find_candidates_everywhereRun the database match and the outside search together and keep the two lists apart.
Takes: requisition_id, brief, limit=10, role_title, locations, skills, seniority, industries, min_years (all optional)
Returns: in_book, ranked with checklists, and outside, with work history and no contact details, plus a note. If outside search is off, in_book still comes back with the reason.
Credits: The outside half uses the monthly outside-search allowance; the database half is free
Read scope, but it holds search allowance and saves what it finds. Recruiter or admin only.
create_candidate_profilesFile people found by outside search as candidates, optionally onto a role.
Takes: result_ids (up to 50), requisition_id=None, find_email=False
Returns: Which people were created, which were linked to an existing record, the role they were added to, anyone skipped because their row on that role is closed, and the email lookup summary.
Credits: Free to create. With find_email, up to 4 credits each, charged only when an email is found
enrich_candidateLook for a candidate's email address, personal first and then work.
Takes: candidate_id
Returns: A status of queued or skipped with the reason, the estimate and the credits remaining. The email arrives on the record later.
Credits: Up to 4 credits, charged only when an email is found
find_candidate_contact_infoLook up a candidate's email and, only if the user asked, their mobile number.
Takes: candidate_id, fields=None (email, work_email, personal_email, mobile)
Returns: A status of queued or skipped, the fields asked for, the estimate and the credits remaining. Nothing is returned directly; read the record afterwards.
Credits: Email up to 4, work email 1, personal email 3, mobile 10. Charged only for what is found
How outside search works
search_outside_book looks for people your agency does not have yet and returns names, current titles and companies, locations, LinkedIn addresses, work history, years of experience and, when there is a role, a fit score with the reasons for it. It never returns an email address or a phone number, and people already in your database are left out. find_candidates_everywhere asks both questions at once and keeps the two answers in separate lists, in_book and outside, so the assistant can say which list a person came from.
When nobody matches every filter, the search runs again with the industry, then the seniority, then the location dropped, and the response says which were dropped. The assistant is expected to tell the user, and never to present those people as matching everything. Searches are limited each month, so a tool that was asked for a page of ten should not be called speculatively.
From a name to a way to reach them
Filing someone found outside is free: create_candidate_profiles turns result ids into candidates, links anyone who already exists instead of duplicating them, and can put each onto a role's pipeline at the first stage. Contact details are a separate, deliberate step. find_candidate_contact_info queues a lookup and the result lands on the record within a minute or two, read afterwards with get_candidate. A mobile number is the dearest field at 10 credits and is only to be requested when the user asked for one. Credits are charged only when something is found, and a lookup is skipped at no cost for someone with the detail already, marked do not contact, or opted out of email.
What to ask
These are the kind of messages a recruiter types into Claude or ChatGPT once Vayora is connected. The assistant chooses the tools itself.
- Find me Heads of Engineering in Leeds with a fintech background who are not already in our database.
- For the Senior Backend role, show who we have and who we do not, as two separate lists.
- File the first three people from that search as candidates on the role, but do not look up any contact details yet.
- Look up an email for the second one. I do not need a mobile.
Common questions
- Do these tools spend credits?
- The lookups do, and each states its price: up to 4 credits for a candidate email, 1 for a work email, 3 for a personal email and 10 for a mobile. A credit is charged only when something is found. Filing people as candidates is free, and the outside search draws on a separate monthly search allowance.
- Does an outside search return email addresses?
- No. Outside results carry work history, titles, locations and LinkedIn addresses, never an email or a phone number. Contact details are a separate lookup the user has to ask for.
- What stops an assistant spending credits on its own?
- The tools are flagged for the host as reaching outside your data and, for the two searches, as not read-only, so Claude and ChatGPT ask before running them. The tool text also tells the model never to request a mobile unless the user asked. Lookups need the write scope, which the person grants when they connect.
- Who can run the outside search?
- A recruiter or an admin. It also depends on your plan and on outside search being switched on for the workspace. When it cannot run, find_candidates_everywhere says why and still returns the people already in your database.
Every tool acts as the person who connected it, inside their own workspace. The MCP overview covers connecting, the read and write split and limits. The developers page has the API and webhooks, integrations lists the rest of what Vayora connects to, and ATS or CRM for a recruitment agency explains why the records sit in one place. To try it on your own book, start a free trial.