Spott

Kick off external enrichment (email, phone, LinkedIn, or full profile) for a candidate via the configured data provider. Returns the provider response or a delayed request id.

spott_enrich_candidate

Enroll one or more candidates into an outreach campaign. Accepts either campaignId or campaignName; the tool resolves the name to an id. Reversible (un-enroll via campaign management).

spott_enroll_in_campaign

Have Spott generate a full job description for a job from its current fields. Replaces the entire content of the job description in that language, discarding whatever was there before, and creates one only when that language has none yet. Generation is synchronous: this returns once the new job description has been generated and saved. It always uses the tenant default JOB_DESCRIPTION template matching the job description format.

spott_generate_job_description

Fetch activity entries for an application: stage changes, interviews logged, scorecard submissions, comments added.

spott_get_application_activity

Fetch internal comments on an application. Page-paginated.

spott_get_application_comments

Fetch recent activity entries (interactions, status changes, notes) for a candidate. Cursor-paginated.

spott_get_candidate_activity

Fetch all applications a candidate has — both standard (linked to a job) and speculative (linked directly to a company).

spott_get_candidate_applications

Fetch a candidate's professional certifications.

spott_get_candidate_certifications

Fetch all contact identifiers (emails, phone numbers, social profiles) for a candidate.

spott_get_candidate_contact_identifiers

Fetch a candidate's education history: schools, degrees, fields of study, dates.

spott_get_candidate_education

List the email/SMS/WhatsApp interaction history with a candidate, newest first. Returns paginated UniboxInteractionDto items (subject, snippet, direction, timestamp). Use to scroll through prior conversation when the user asks "did I discuss X with Jean?" — combine with spott_get_notes_for_record for the full picture.

spott_get_candidate_emails

Fetch a candidate's full work history with stats. Returns roles, companies, dates, descriptions.

spott_get_candidate_work_experiences

Fetch recent activity entries (interactions, status changes, notes) for a company. Cursor-paginated.

spott_get_company_activity

List company contacts (hiring managers, BD contacts) tied to a company. Cursor-paginated.

spott_get_company_employees

Get notes attached to a single record (candidate, company, company contact, job, application, or opportunity), optionally filtered by a free-text query against title + content. Use to answer "did I discuss X with Jean?" — pass jeanCandidateId as scopeId and the topic as searchQuery. Returns paginated NoteDto items with title, content, source (phone / inPerson / onlineMeeting / callAttempted), and createdBy.

spott_get_notes_for_record

Batch-fetch base records by id. Returns the core entity DTO only (e.g. candidate profile, vacancy fields, application stage/owner/scorecard). Heavy sub-resources — work history, activity, comments, employees — are NOT included; call the matching spott_get_<resource> drill-down tool for those.

spott_get_records_by_ids

Imports a CV / resume into Spott as a new candidate. **This is the ONLY correct way to import a CV.** Do NOT fall back to `spott_create_candidate` if this flow fails — surface the error to the user instead so they can fix it. Accepted file formats (and their required `Content-Type` headers): - PDF → `application/pdf` - Word (.docx) → `application/vnd.openxmlformats-officedocument.wordprocessingml.document` - Word 97-2003 (.doc) → `application/msword` - Plain text (.txt) → `text/plain` This tool DOES NOT accept the file contents directly. It returns a short-lived signed `uploadUrl`. To complete the import, use an available file or code-execution capability to PUT the raw CV bytes to that URL. Required steps: 1. Call this tool. It returns `{ uploadUrl, expiresAt, acceptedMimeTypes, requiredAllowedDomain }`. 2. Send `PUT <uploadUrl>` with: - the **raw binary** body of the CV (no base64, no JSON wrapping, no multipart envelope), - header `Content-Type` set to the value matching the file format from the list above, and - header `Content-Length` set to the file's byte length. 3. **READ THE PUT RESPONSE BODY.** On success it is JSON of the form `{"candidateId":"<uuid>","uploadId":"<uuid>"}`. The `candidateId` is the id of the candidate that was just created from the CV — report that id to the user. No further MCP tool call is needed. 4. On error the response is JSON `{"error":"<code>","message":"<reason>"}` with a non-2xx status — surface the message to the user. **NETWORK ACCESS REQUIREMENT.** The PUT goes to `mcp.spott.io`. If the PUT fails because the available file or code-execution capability restricts outbound network access, tell the user to allow `mcp.spott.io` in that capability's network settings (an "allowed domains" / allowlist option, where the client offers one) and to retry once it is allowed. Do not retry repeatedly or call another tool as a substitute. Once network access is available, call this tool again to mint a fresh `uploadUrl` before retrying. Strictly forbidden: - Do NOT base64-encode the file. Do NOT pass file contents in any tool argument or chat message — the bytes go in the PUT body, nowhere else. Sending base64 wastes tokens and will not work. - Do NOT use POST. Do NOT use multipart/form-data. The body is the raw bytes. - Do NOT reuse an `uploadUrl` after a successful PUT — request a new one for each file. - Do NOT silently fall back to `spott_create_candidate` or any other tool when this flow fails. The user explicitly asked to import a CV; tell them what's wrong. Constraints: max 10 MB per CV. The `uploadUrl` expires 5 minutes after issuance.

spott_import_candidate_from_cv

Look up tenant-configured reference data needed as ids by other tools. Returns slim {id, name} records (with extras per type). Sets: application_stages, vacancy_stages, opportunity_stages, company_stages (shared by companies and company contacts), company_industries (a flat array of industry label strings — not {id, name} — to pass verbatim to spott_create_company / spott_update_company), rejection_labels, task_labels, users, candidate_lists, company_lists, company_contact_lists, custom_fields_<entity> for candidate/job/company/opportunity. For first-class records (campaigns, candidates, jobs, etc.) use spott_search_records.

spott_list_enums

Log a phone call retrospectively on a candidate or company contact as a note (source=phone).

spott_log_call

Advance one or more applications to a new pipeline stage. Look up valid stage ids via spott_list_enums application_stages.

spott_move_application

Today's plate for the authenticated recruiter: incomplete tasks assigned to them with a due date in the next N days (default 7), plus upcoming meetings. Returns compact task and meeting summaries; each task summary carries its priority. Tasks are ordered by due date and capped at limit, so this is not a priority ranking.

spott_my_work

Close a deal: advance the application to the "placed" stage and create a v2 placement record (CONTINGENT or INTERIM). Sibling applications on the same job are NOT auto-rejected — use spott_reject_application for that. Defaults to dry_run.

spott_place_candidate

Tenant-wide autocomplete across candidates, jobs, companies, contacts, opportunities, teams, and users. Use when you have a name fragment and need to disambiguate before calling a more specific tool. Pass only the distinguishing words: every one must occur in the record, in any order, so extra words make it miss. Small misspellings of the whole name are tolerated; opportunities also match their client company name.

spott_quick_lookup

Reject one or more applications with a labeled reason and optional note. Pass reasonLabel as text — the tool resolves it to an id. Reversible (un-reject is supported elsewhere).

spott_reject_application

Schedule an interview on an application: create a calendar event with the given user attendees and link it to the application. The created event can be deleted to undo.

spott_schedule_interview

Free-text search across Spott records. objectType selects the entity (candidate, job, company, application, opportunity, campaign). scopeId narrows results: candidate/company = saved list id; job/opportunity = saved view id (chooses the returned columns, not which rows); application = job id (required for free-text search on applications); campaign = unused. Returns paginated rows; use spott_get_records_by_ids for full detail. For opportunity, searchQuery matches a substring of the name only — use spott_quick_lookup to resolve a name to an id.

spott_search_records

Send an email to one or more recipients (candidate, company contact, internal user, or raw external address). Supports cc, bcc, and attachments. Defaults to dry_run which returns a rendered preview with signature applied; set dry_run=false to actually send.

spott_send_email

Set a custom field value on one or more records. Use spott_list_enums to discover the definitionId, the definition's viewType, and the valid option labels. The "kind" you pass MUST match the definition's viewType, otherwise the write is rejected: drop the "custom" prefix and lowercase the first letter (customDate -> date, customMultiEntity -> multiEntity). Supported kinds: text, number, checkbox, date, timestamp, rating, select, multiSelect, currency, dateRange, duration, url, entity, multiEntity.

spott_set_custom_field

Submit one or more attribute scorecard rows for an application. Pass attributeScores to write manually, or autoGenerate=true to have Spott infer scores from the interview transcript in the given language.

spott_submit_interview_score

Partially update a candidate. Only provided fields change; email and phone arrays fully replace existing values if supplied.

spott_update_candidate

Partially update a company (client): company info (name, domain, description, linkedinUrl, industry, size) and/or its pipeline stage. Only provided fields change. Pass null on nullable fields to clear them.

spott_update_company

Partially update a company contact. Only provided fields change; email/phone arrays fully replace existing values if supplied. Set endDate to mark the contact as having left the company. The LinkedIn URL lives on the candidate record backing the contact — change it with spott_update_candidate using the contact's candidateId.

spott_update_company_contact

Partially update a job. Only provided fields change. Pass null on nullable fields to clear them.

spott_update_job

Partially update an opportunity. Only provided fields change. Pass null on nullable fields to clear them.

spott_update_opportunity

Update an existing task. Only the fields you pass change; everything else (content, due date, priority, links, labels) is preserved. Pass null on nullable fields to clear them.

spott_update_task

Return the authenticated user id and tenant/org id. Useful as a sanity check before write operations or when defaulting assigneeUserId/ownerId.

spott_whoami