When to use it
- “Take the 40 VPs I just pulled from HubSpot and get them ready to invite to the LA dinner.”
- “Import this Sales Navigator export with each person’s city.”
- “Load my CRM list in chunks, then save it as a List.”
- “Mark which of these my teammate Tony already knows.”
Parameters
location is where the person is, as the source states it. Never pass a company address and never coordinates. The city is stored as stated and never geocoded.
Workflow
1
Preview the first chunk
Call
action: "preview" with up to about 50 people and a fresh client_request_id. Nothing is imported. Read row_outcomes, workspace_overlap and company_carry.2
Tell the user what the preview found
Relay
workspace_overlap.sentence and company_carry.sentence as written. Offer each candidates_by_name entry for the user to confirm. Never call two emails the same person on your own. Name any suspect_rows.3
Append the rest
For more people, call
action: "append" with the import_token, the next chunk and a fresh client_request_id. Report the staged totals, never one chunk’s. At most 2,000 people staged in all.4
Confirm once
After the user agrees, call
action: "confirm" with the import_token, a fresh client_request_id and no people. It imports every staged person once.5
Save the List
Pass
data[0].member_emails to save_list unchanged.client_request_id. A committed import is replayed (idempotent_replay: true), never repeated.
Response
Per person, by email (case-insensitive): someone the workspace already holds is merged (nothing overwritten), an erased person is rejected and stays erased, a malformed address is rejected, anyone else is created.
This sample is trimmed from a real preview of fictional example.org people sent today. Nothing was imported.
Rules the agent must follow
- Preview first, show the user, and confirm only after they agree.
- Relay
workspace_overlap.sentenceandcompany_carry.sentenceas written. - Never merge two emails as one person without the user’s confirmation.
- Leave a suspect row out of save_list only if the user agrees. Never exclude anyone on your own.
- Never treat an import as evidence that anyone registered or attended.
- Never pass a company’s address as a person’s
location.
Errors and gaps
-
Rejected rows are disclosed in
gaps. Correct a malformed address and send it in a laterappend. Do not re-import an erased person. -
invalid_parameter: a person carries a key this tool does not accept,peopleis empty or over 500,source_systemis missing beside anexternal_id, or a chunk was sent again under a newclient_request_id. -
insufficient_scope: the OAuth token lacksmcp:tools:write. Nothing is imported. - Writing needs no plan: every workspace can write.
-
internal_error: retry once with the sameclient_request_id.
Related
- save_list: keep the imported people as a List.
- check_people: see what the workspace already knows before importing.
- activate_list: invite the List.
- Playbook: Fill the room in the two weeks before.