Sweepy MCP tool reference

The MCP server in server.py exposes twelve tools. The MCP integration page covers registration and common workflows. This page lists every signature, so you can predict what a call does before an assistant runs it.

Response payload

Each tool returns a JSON string inside a text content block. Success payloads start with "status": "ok". Failure payloads start with "status": "error" and include a message that explains the cause. A failed sweep also reports job_id and sweep_status: "failed".

Behavior hints

Sweepy declares four MCP annotations on every tool. A compatible host reads these hints before it invokes the tool.

Hint	Meaning
readOnlyHint	The call doesn't persist changes.
destructiveHint	The call can overwrite or delete files, profiles, or history.
idempotentHint	Repeating the same call reaches the same end state.
openWorldHint	The call reaches beyond the local machine.

Tool	Read-only	Destructive	Idempotent	Open world
create_profile	No	Yes	Yes	No
run_sweep	No	Yes	No	Yes
get_sweep_status	No	No	Yes	No
get_jobs	No	No	Yes	No
submit_judgments	No	Yes	Yes	No
import_jobs	No	Yes	Yes	Yes
render_report	No	Yes	Yes	No
get_results	Yes	No	Yes	No
export_report	No	Yes	Yes	No
clear_history	No	Yes	Yes	No
convert_document	No	Yes	Yes	No
convert_docx	No	Yes	Yes	No

Profile and sweep tools

create_profile

Validates each enabled engine, then writes the profile YAML file.

Parameter	Type	Default	Description
name	string	Required	Full name written to the profile.
titles	string array	Required	Target job titles, such as ["Technical Writer", "UX Writer"].
location	string	Required	Target location, such as "New York, NY".
resume_path	string	Required	Path to a PDF or DOCX resume.
remote_only	boolean	false	Restricts results to 100% remote roles.
include_hybrid	boolean	true	Keeps hybrid roles in the results.
min_salary	integer	0	Minimum annual base salary. Zero means no minimum.
must_have_skills	string array	null	Skill terms that boost matching.
synonyms	array of arrays	null	Interchangeable term groups, such as [["docs-as-code", "documentation as code"]].
platforms	object	null	Platform switches merged into the profile's platforms block.
sources_config	object	null	Engine selection merged into the sources block. Every engine validates before the write.
cache_config	object	null	Cache settings: enabled and ttl_seconds.
orchestrator_config	object	null	Timeout and circuit-breaker settings.
history_config	object	null	Cross-run settings that control which postings the sweep skips.
job_tracking	boolean	true	Add the job-tracking columns to the CSV and carry earlier values forward.
assessment	string	"agent"	Report gate. agent blocks a report while any card has keyword overlap alone. keyword permits keyword-only reports.
output_filename	string	null	Custom YAML path. Defaults to profiles/{name}_{title}.yaml. Sweepy lowercases both parts and replaces every non-alphanumeric character with _.

orchestrator_config takes timeout_per_source_seconds and a circuit_breaker object with failure_threshold and cooldown_seconds.

history_config takes enabled, retention_days, match, and path. retention_days defaults to 4, match accepts url or url+role, and path defaults to ~/.sweepy/history.db.

Returns profile_path, enabled_engines, and engines_not_enabled.

run_sweep

Starts the five-stage pipeline and returns deterministic keyword-overlap scores. It doesn't invoke LLM judgment.

Parameter	Type	Default	Description
profile_path	string	null	Path to the profile YAML. When omitted, Sweepy uses the last saved profile, then the first conventional profile on disk: profiles/custom_profile.yaml, profiles/paralegal_nyc.yaml, or config.sample.yaml.
deduplicate	boolean	true	Merges repeated URLs and matching postings from different boards for this run.
include_seen	boolean	false	Reports postings from earlier sweeps and refreshes their history.
wait_seconds	integer	45	Longest blocking wait before the call returns progress. Clamped to the range 0 to 600.

A live sweep often runs longer than a client timeout. The pipeline handles that gap by running on a background thread. A call that returns sweep_status: "running" includes a job_id. Pass that id to get_sweep_status until the status reads completed.

A second call with the same profile and flags attaches to the running job instead of starting another. The server process must stay running. Sweep job ids live in memory. A restart clears them.

Returns one of three payloads:

• Running: sweep_status, job_id, progress with step, total, and label, plus elapsed_seconds, debug_log, and message.
• Completed: sweep_status, job_id, discovered_count, new_count, previously_seen_count, active_count, top_match, top_roles, reports, job_ids, card_count, assessed_count, assessment_mode, assessment_required, skipped_sources, elapsed_seconds, debug_log, and message. top_roles holds the first five roles.
• Failed: status: "error", message, job_id, and sweep_status: "failed".

A missing or unreadable profile path fails before a job starts. That error has no job_id.

When every discovered posting is a repeat, previously_seen_count reports the total and active_count reports zero. Call run_sweep with include_seen set to true to review them.

get_sweep_status

Waits on a sweep that run_sweep started and reports its progress.

Parameter	Type	Default	Description
job_id	string	null	Sweep id from run_sweep. Defaults to the most recent job.
wait_seconds	integer	45	Longest blocking wait before the call returns progress. Clamped to the range 0 to 600.

Each response returns the same fields as the matching run_sweep result. A missing or unknown job_id returns an error that points back to run_sweep.

A finished sweep also loads its cards into the live session, so get_jobs, submit_judgments, and render_report work once the status reads completed.

get_jobs

Returns the card records held in the current session, ranked by keyword overlap or submitted match score.

Parameter	Type	Default	Description
profile_stem	string	null	Profile identifier used to load a saved session, such as pedro_writer.
results_dir	string	"results"	Folder that holds report_session.json.
limit	integer	null	Number of cards to return. Omit it to return every card. Sweepy enforces a minimum of one.

Returns count and jobs. While a sweep runs, the payload adds sweep_status, running_job_id, progress, and a message that warns the cards predate that sweep.

submit_judgments

Merges an assistant's assessment into one card or a whole batch. Only non-null fields change.

Parameter	Type	Default	Description
job_id	string	null	Stable card id from run_sweep or get_jobs. Required unless you pass judgments.
match_pct	integer	null	Match percentage from 0 to 100. Supplying it changes the card label to MATCH.
resume_track	string	null	Resume track to display on the card.
resume_color	string	null	Badge color for that track.
domain	string	null	Role domain shown on the card.
summary	string	null	Card summary text.
requirements	string	null	Requirements text.
alignment	string	null	Note that connects the resume evidence to the role.
has_extended_response	boolean	null	Flags a posting that requires written answers.
app_format	string	null	App format, such as a portal or an email.
comp	string	null	Compensation line.
benefits	string	null	Benefits line.
page_theme	string	null	Card theme override.
judgments	array	null	List of judgment objects, each with a job_id plus any field preceding. Don't combine it with job_id.

Returns the merged card as job. A batch returns applied, jobs, and rejected, where rejected names any entry whose id is missing from the session.

import_jobs

Adds roles that independent research found and verified. Sweepy doesn't confirm them by default.

Parameter	Type	Default	Description
jobs_json	string	Required	JSON array of card records.
validate	boolean	false	Runs each URL through the link checker before import.

Returns imported and skipped. A rate limit or bot-protection response counts as unverified, so it doesn't prove a posting is dead.

render_report

Renders the cards PDF from the current session.

Parameter	Type	Default	Description
profile_stem	string	null	Profile identifier used to load a saved session.
results_dir	string	"results"	Folder for the default output and the saved session.
output_filename	string	null	Explicit PDF path. It must stay inside the workspace.
playbook	string	""	Plain-text strategy note. Sweepy escapes & and angle brackets, and it renders **bold** as bold. Newlines become line breaks. Sweepy saves the text with the session, so a later call without it reuses the saved text. An empty value with no saved text generates a deterministic playbook.

Returns pdf_report, pages, card_count, and playbook_saved.

Profiles default to report.assessment: "agent", which blocks the render while any card has only keyword overlap. The error lists unassessed_job_ids and unassessed_titles so the assistant knows what to judge. Set report.assessment: "keyword" to allow mixed reports, or SWEEPY_REQUIRE_JUDGMENTS=1 to apply the gate to every profile and to export_report.

Results and history tools

get_results

Reads the latest sweep JSON from disk. It never re-runs discovery or scoring.

Parameter	Type	Default	Description
profile_stem	string	null	Profile identifier that filters the result files. Omit it to read the newest result file.
results_dir	string	"results"	Folder that holds the result files.
limit	integer	10	Number of top roles to return. Clamped to the range 1 to 100.

Returns result_file, pdf_report, csv_report, total_roles, and top_roles. Each role contains title, company, location, match_score, match_kind, resume_track, domain, url, and playbook.

Scores labeled KEYWORD OVERLAP are deterministic first-pass values. Use get_jobs and submit_judgments before you present them as matches.

export_report

Rebuilds report files from an existing sweep JSON.

Parameter	Type	Default	Description
json_source	string	null	Path to the sweep JSON. It takes priority over profile_stem.
profile_stem	string	null	Profile identifier used to find the latest matching JSON.
results_dir	string	"results"	Folder that holds the result files.
formats	string array	["pdf"]	Output formats: pdf, png, csv, or json.
candidate_name	string	"Job Seeker"	Name in the PDF header.
output_dir	string	null	Output folder. Defaults to the folder that contains the source JSON.
job_tracking	boolean	null	Add the job-tracking columns to a CSV export. Leave unset to follow the profile's export.tracking setting.

Returns source_file, roles_exported, generated, and errors. The generated object holds pdf, pdf_pages, png, csv, csv_rows, and json when the request includes those formats. A PNG request renders the PDF first. JSON output writes {stem}_export.json, so it never overwrites the sweep file that feeds it.

clear_history

Forgets reported postings so the next sweep can report them again.

Parameter	Type	Default	Description
profile_path	string	null	Path to the profile YAML.
profile_stem	string	null	Profile identifier, such as pedro_writer.

Returns scope, cleared, and remaining. Histories are per profile. Call the tool with neither parameter after a sweep to clear the profile that sweep used. That fallback reads state from the running server, so pass profile_path or profile_stem after a restart.

Document conversion tools

convert_document

Converts .docx, .doc, .txt, .md, or .pdf to PDF. A PDF source passes through unchanged. Legacy .doc files need Microsoft Word.

Parameter	Type	Default	Description
document_path	string	Required	Path to the file to convert.
pdf_path	string	null	Output path. Defaults to the source folder.

Returns pdf_path and source_path.

convert_docx

Converts a DOCX resume to PDF with python-docx and reportlab. When Microsoft Word is available, it falls back to docx2pdf.

Parameter	Type	Default	Description
docx_path	string	Required	Path to the .docx file.
pdf_path	string	null	Output path. Defaults to the DOCX folder.

Returns pdf_path.

Write paths

Tools that write keep their output inside the Sweepy folder. A target outside that folder fails until you set SWEEPY_ALLOW_EXTERNAL_WRITES to 1. Reads accept any path the process can open.