MCP tool reference

The client discovers exact input schemas through MCP tools/list. This reference covers all 30 tools. See permissions for scope descriptions and filters for the complete filter and contact schema.

Shared arguments

• IDs (job_id, list_id, lead_id, status_id, member_id, invite_id) are UUIDs returned by the relevant tools.
• Every mutation requires a request_id UUID. Reuse that ID with identical arguments when retrying the same operation. Use a new UUID only for a new intended operation, including each new page being saved or looked up.
• Where listed, offset starts at 0 and defaults to 0; limit defaults to 100 and accepts 1–500. Maximum offset is 1,000,000.
• Optional arguments are marked with ?. Unlisted arguments are rejected.

Account and search

Tool	Arguments	Permission / behavior
get_account	None	mcp:read; selected account, user, permissions, plan, credit balances
get_search_filters	None	mcp:read; filter schema, examples, suggestions
preview_leads	filters, page?, limit?	mcp:read; free masked preview. Page 1–10,000 (default 1); limit 1–100 (default 25)
get_search_count	filters	mcp:read; free count with exact/estimated indicators
search_leads	request_id, filters, max_results	leads:search; create a paid asynchronous search, max 1–100,000 results
list_search_jobs	offset?, limit?	mcp:read; recent account/team search jobs
get_search_job	job_id	mcp:read; existing job progress and errors
get_search_results	job_id, offset?, limit?	mcp:read; existing paid results with complete payloads; no new charge
cancel_search_job	request_id, job_id	leads:search; cancel a queued job only
lookup_linkedin	See below	leads:search; paid LinkedIn contact lookup

LinkedIn lookup arguments

Required: request_id and linkedinUrls (1–500 HTTPS profile URLs at linkedin.com/in/… or www.linkedin.com/in/…).

Optional argument	Default / limits
includePhones	false
includeWorkEmails	true
includePersonalEmails	true
onlyWithEmails	false
perPage	25; 1–100
page	1; 1–500
maxResults	500; 1–500

Use the same request ID when retrying one page. A different page is a different operation and needs a different request ID. Only returned matches spend credits.

Lists and contacts

Tool	Arguments	Permission / behavior
list_lists	offset?, limit?	mcp:read; account/team lists
get_list	list_id	mcp:read; list metadata and saved filters
create_list	request_id, name, list fields below	lists:write; plan list limits apply
update_list	request_id, list_id, changes	lists:write; partial list fields
delete_list	request_id, list_id	lists:write; delete list; contacts become unassigned
get_list_leads	list_id, offset?, limit?	mcp:read; saved contacts, including lead_data
save_search_results	request_id, list_id, job_id, offset?, limit?	lists:write; save a page of existing results with all fields; deduplicates by list/job/result position
add_leads_to_list	request_id, list_id, leads	lists:write; 1–100 supplied contact objects
update_saved_lead	request_id, lead_id, changes	lists:write; contact fields only; ownership and billing fields cannot change
delete_saved_leads	request_id, lead_ids	lists:write; remove 1–100 specified contacts
export_list_file	list_id, format?, columns?	leads:export; whole-list download link in csv (default), json, or jsonl; no extra credits
export_list	list_id, offset?, limit?, format?	leads:export; paginated json (default) or csv, no extra credits

Download a complete file

Prefer export_list_file when the user wants a downloadable file. It returns download_url, filename, mime_type, row_count, and expires_at, plus an MCP resource link. Give the link to the user or download it with your client tools. Dievio handles pagination; no browser login or extra Authorization header is needed.

Optional columns selects and orders up to 60 fields, including nested paths such as lead_data.company_website. Without this option, CSV includes the standard contact fields plus the complete lead_data JSON column. JSON/JSONL retain complete saved rows. Selected nested paths become literal property names in JSON/JSONL. CSV uses UTF-8 with BOM for Excel and neutralizes spreadsheet formulas.

The link is private, scoped to this list and format, and expires within 15 minutes (or sooner if the connection expires). Do not publish it. Revoking the connection, removing a member, or deleting the list stops access. Files reflect the list at download time; avoid changing the list during a download. An interrupted or expired download needs a new link and retry.

Maximum: 100,000 contacts per file and 10 download starts per minute per connection. Split larger lists. XLSX is not a built-in format; CSV opens in Excel.

List fields

name is required for creation (1–200 characters). Optional fields:

• description: nullable string, up to 5,000 characters.
• status: active, needs_review, qualified, ready_export, paused, or archived.
• status_label: nullable string, up to 120 characters.
• status_color: nullable six-digit hex color, such as #14b8a6.
• search_filters: the complete filter object, or null.

Updating lead_data or search_filters replaces that object's value; preserve existing fields you want to keep. Deleting a list does not delete its saved contacts. Deleting saved contacts is a separate action.

Status definitions

Tool	Arguments	Permission / behavior
list_statuses	None	mcp:read; reusable labels and colors
create_status	request_id, label, color	lists:write; label 1–120 characters; six-digit hex color
update_status	request_id, status_id, label, color	lists:write; change reusable definition
delete_status	request_id, status_id	lists:write; remove definition without deleting lists

Lists store their label and color separately. Updating a reusable status does not automatically change existing lists; use update_list for those.

Team management

Tool	Arguments	Permission / behavior
get_team	None	mcp:read; team members; pending invitations visible to the owner only
invite_team_member	request_id, email	Owner + team:manage; sends invitation email; seat limits apply
remove_team_member	request_id, member_id	Owner + team:manage; remove member and revoke their team agent access
cancel_team_invitation	request_id, invite_id	Owner + team:manage; expire a pending invitation

Reference resources

• dievio://guide/agent-workflows — workflow, credit, team, and retry guidance in plain text.
• dievio://schema/search-filters — all supported search filters and suggestions as JSON.

Clients that do not expose MCP resources can use get_search_filters and these documentation pages instead.