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. Creates the description record if one does not exist yet and kicks off generation. promptTemplateId defaults to the tenant default JOB_DESCRIPTION template if omitted.

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.

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, and users. Use when you have a name fragment and need to disambiguate before calling a more specific tool.

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; application = job id (required for free-text search on applications); campaign = unused. Returns paginated rows; use spott_get_records_by_ids for full detail.

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, 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