spott_add_note
ChatGPTCreate a note linked to one or more records (candidate, company, job, application, etc.). Supports @-mentions in content.
Business & Operations
Overview
Spott helps recruiting teams find and manage candidates, companies, jobs, applications, interviews, tasks, notes, outreach, and placements through ChatGPT.
Tools
spott_add_to_list
ChatGPTAdd one or more records to a named list (candidate pool, company list, or company-contact list). Lists are manual collections recruiters curate for targeted outreach or reporting.
spott_complete_task
ChatGPTMark a task as completed (or re-open it). Idempotent.
spott_create_application
ChatGPTCreate an application linking a candidate to a job (standard) or directly to a company (speculative). Supply jobId OR companyId, not both.
spott_create_candidate
ChatGPTCreate a new candidate manually with name and optional contact identifiers. Returns the new candidate id.
spott_create_company
ChatGPTCreate a new company (client) record with its core company info and optional pipeline stage. Returns the new company id. Check for an existing company first with spott_quick_lookup or spott_search_records to avoid duplicates.
spott_create_company_contact
ChatGPTCreate a new company contact (a person working at a company, e.g. a hiring manager, HR or BD contact): person details plus their role at that company. Use spott_create_candidate instead for job seekers. Spott also creates a linked candidate record backing the contact, so both ids are returned. Check spott_get_company_employees / spott_quick_lookup first to avoid duplicates.
spott_create_job
ChatGPTCreate a new job tied to a company. Returns the job id. Optionally seeds a briefing note from intake.
spott_create_opportunity
ChatGPTLog a business-development opportunity on a company: expected value, target stage, decision window.
spott_create_task
ChatGPTCreate a task with optional due date, assignee, and linked entities (candidate/company/job/etc). Priority defaults to NONE when omitted, so pass it whenever the task should carry one.
spott_enrich_candidate
ChatGPTKick 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_enroll_in_campaign
ChatGPTEnroll 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_generate_job_description
ChatGPTHave 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_get_application_activity
ChatGPTFetch activity entries for an application: stage changes, interviews logged, scorecard submissions, comments added.
spott_get_application_comments
ChatGPTFetch internal comments on an application. Page-paginated.
spott_get_attachment_content
ChatGPTReturn the text Spott extracted from one file at upload. Ids come from spott_get_attachments_for_record or a candidate's cvAttachmentId. A file without extracted text returns an error saying so, not an empty file. Returns the text in pages of up to 8000 characters, plus totalChars; when cursor is not null, call again with that cursor to read the next page.
spott_get_attachments_for_record
ChatGPTList the files attached to one record (candidate, job, company or opportunity), paginated. Returns metadata only: id, name, extension, type, size, createdAt. To read a file's text, pass its id to spott_get_attachment_content. A candidate's CV id is also available directly as cvAttachmentId on the candidate.
spott_get_candidate_activity
ChatGPTFetch recent activity entries (interactions, status changes, notes) for a candidate. Cursor-paginated.
spott_get_candidate_applications
ChatGPTFetch all applications a candidate has — both standard (linked to a job) and speculative (linked directly to a company).
spott_get_candidate_certifications
ChatGPTFetch a candidate's professional certifications.
spott_get_candidate_contact_identifiers
ChatGPTFetch all contact identifiers (emails, phone numbers, social profiles) for a candidate.
spott_get_candidate_education
ChatGPTFetch a candidate's education history: schools, degrees, fields of study, dates.
spott_get_candidate_emails
ChatGPTList 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_work_experiences
ChatGPTFetch a candidate's full work history with stats. Returns roles, companies, dates, descriptions.
spott_get_company_activity
ChatGPTFetch recent activity entries (interactions, status changes, notes) for a company. Cursor-paginated.
spott_get_company_employees
ChatGPTList company contacts (hiring managers, BD contacts) tied to a company. Cursor-paginated.
spott_get_notes_for_record
ChatGPTGet 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_records_by_ids
ChatGPTBatch-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_transcript
ChatGPTGet the full transcript of a meeting, a phone call or an in-person recording. Where each id comes from: note.meeting.id, note.call.id and note.audioRecording.id from spott_get_notes_for_record; meetingWithCandidate.meetingId and callWithCandidate.call.id from spott_get_candidate_activity; callWithClientContact.call.id from spott_get_company_activity; meeting id from spott_list_meetings. Returns the text as 'Speaker: text' lines in pages of up to 8000 characters, with totalChars and cursor; when cursor is not null, call again with that cursor to read the next page. With includeTimestamps, lines get a [mm:ss - mm:ss] prefix only when the transcript has a speaker timeline; otherwise they come back without timestamps. A missing or unfinished transcript comes back as an error, not an empty conversation.
spott_import_candidate_from_cv
ChatGPTImports 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_list_enums
ChatGPTLook 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_meetings
ChatGPTList the authenticated user's own calendar meetings, past and future, that start between from and to (ISO-8601; at most 366 days apart), oldest first, paginated. Only meetings the user takes part in are returned. Each item has id, title, start and end time, participants (name, email) and hasTranscript; when hasTranscript is true pass the id to spott_get_transcript with scopeType 'meeting'. An id of null is an occurrence of a recurring series that is not stored as its own meeting (past or future), so it has no transcript. Phone calls and in-person recordings are not listed here: use spott_get_candidate_activity / spott_get_company_activity with sources ['calls'], or spott_get_notes_for_record.
spott_log_call
ChatGPTLog a phone call retrospectively on a candidate or company contact as a note (source=phone).
spott_move_application
ChatGPTAdvance one or more applications to a new pipeline stage. Look up valid stage ids via spott_list_enums application_stages.
spott_my_work
ChatGPTToday'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_place_candidate
ChatGPTClose 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_quick_lookup
ChatGPTTenant-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_reject_application
ChatGPTReject 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_schedule_interview
ChatGPTSchedule 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_search_records
ChatGPTFree-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_send_email
ChatGPTSend 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_set_custom_field
ChatGPTSet 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_submit_interview_score
ChatGPTSubmit 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_update_candidate
ChatGPTPartially update a candidate. Only provided fields change; email and phone arrays fully replace existing values if supplied.
spott_update_company
ChatGPTPartially 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_contact
ChatGPTPartially 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_job
ChatGPTPartially update a job. Only provided fields change. Pass null on nullable fields to clear them.
spott_update_opportunity
ChatGPTPartially update an opportunity. Only provided fields change. Pass null on nullable fields to clear them.
spott_update_task
ChatGPTUpdate 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_whoami
ChatGPTReturn the authenticated user id and tenant/org id. Useful as a sanity check before write operations or when defaulting assigneeUserId/ownerId.
Capabilities
Writes
