manage_ai_prospecting

Manage a per-user shadow copy of an AI Prospecting schema. The shadow lets the caller iterate on regions, keywords, prompts, ranking config, and persona tags in chat, test the draft with ai_prospecting using activate_shadow_run=True, then promote it to live or discard it.

All operations are scoped to the caller — tenant and email come from the OAuth session, never from tool arguments.

When to use it

• “What’s in my prospecting schema?” / “Show me my regions, keywords, ranking config.”
• “Tweak the hot keywords and let me test before going live.”
• “Promote my draft to live.” / “Throw away the draft.”

Lifecycle

get_my_schema → create_shadow → update_shadow (× N) → ai_prospecting(activate_shadow_run=True)
                                                         │
                                                         ├─ happy  → ship_shadow(confirm=True)
                                                         └─ unhappy → discard_shadow

Action	Purpose
get_my_schema	Return {live, shadow} — the source of truth before proposing any edit.
get_shadow	Return just the shadow row (or null).
create_shadow	Copy the caller’s live schema into a new shadow named after the caller’s email.
update_shadow	Apply a patch dict of editable fields. Reversible via discard_shadow.
ship_shadow	Promote shadow → live. Requires confirm=True and an explicit user approval phrase.
discard_shadow	Delete the shadow row. (Shortcut rows revert; edits made on the shortcut path remain.)

Inputs

Parameter	Type	Required	Description
action	enum	Yes	One of the lifecycle actions above.
patch	object	For update_shadow	Dict of editable fields.
confirm	boolean	For ship_shadow	Must be true.
target_tenant_id	string	No	Super tenants only. Scope to another tenant’s schema.
target_user_email	string	No	Super tenants only. Act on behalf of a specific user.

Editable patch fields. included_regions, prospect_match_prompt, ranking_config, hot_keywords, cold_keywords, exclusion_keywords, client_technologies, prompt_modules, prospect_tags_schema, authority_score_threshold, relevancy_filter_prompt, and similar. Protected columns (id, tenant, team, team_members, is_shadow, created_at, updated_at) are rejected server-side.

Returns

JSON with the action’s result or an error field (including status_code when the AI Prospecting service rejected the call).

Notes & rules

• Before create_shadow, call get_my_schema first so you can show the user what is about to be copied and what you plan to change.
• Never call ship_shadow without an explicit user approval phrase (“ship it”, “promote it”, “make it live”) and confirm=True.
• The shortcut path: if the caller is already solo on a schema whose team matches their email domain, create_shadow flips the row to is_shadow=TRUE in place instead of duplicating it. The trade-off is documented: discard_shadow on a shortcut row flips is_shadow back to NULL, but any edits made during testing remain on the live row.
• For super tenants: omit target_user_email on a write action to act as your own authenticated email (auto-assigned to the shadow’s team members), or pass it explicitly to act on behalf of another user.