agent_session
ChatGPTCreate, bind, list, switch project, check, or close a named Super Carl MCP agent session. Call mode="start" when beginning a new external-agent conversation, then pass the returned agent_session_id to later people_search, company_search, jobs_search, posts_search, people_lookup_batch, company_search_batch, send_communication, and project_action calls. Do not use this as the task handler for ordinary user requests like search, send, precheck, shortlist changes, product help, or integration/sync/account-status questions; use the domain tool for the request and pass an existing agent_session_id when available. Tool-result boundary: do not claim a session was found, rebound, closed, or inspected until agent_session returns that result; before the call, say what you are checking or changing, and after the call report only confirmed ids, bindings, and status fields. ID carry-forward: every multi-step session/project workflow must copy the returned agent_session_id and, when present, project_id / session_binding.project_id into later calls. Do not rely on the natural-language project title after a list/status/switch result gives you a stable id. If agent_session exposes API friction, unexpected response shapes, unclear session/project binding, a bug, or user frustration, call super_carl_action with action_id="report_feedback"; report_feedback is non-mutating and does not require user confirmation. mode="start" also returns an orientation block — when orientation.is_first_time is true (or active_project_count is 0), follow the orientation.suggested_topics list and call get_product_help for each before describing Super Carl or running broad searches, so you orient the user in current product vocabulary (the unit of work is a "project") instead of improvising. Use mode="list" when the user wants to resume or check in on an older session. Pass search for natural references such as "Claude", "AI founders", or "recruiter outreach"; results are ordered by most recent activity, so "my Claude session" normally means list with search="Claude" and use the latest clear match. If multiple plausible sessions/projects remain, ask the user to choose before mutating state. Use mode="status" to inspect the active project; its delivery_stall / linkedin_delivery fields distinguish LinkedIn daily-50 cap waits (linkedin_daily_dm_limit_reached, auto-resume/scheduled) from non-limit LinkedIn failures that may need user-confirmed retry. Use mode="switch_project" to point an existing session at a specific project so later session-aware calls can omit project_id. Use the returned agent_session_id as the canonical session id.
agent_session
ChatGPTCreate, bind, list, switch project, check, or close a named Super Carl MCP agent session. Call mode="start" when beginning a new external-agent conversation, then pass the returned agent_session_id to later people_search, company_search, jobs_search, posts_search, people_lookup_batch, company_search_batch, send_communication, and project_action calls. Do not use this as the task handler for ordinary user requests like search, send, precheck, shortlist changes, product help, or integration/sync/account-status questions; use the domain tool for the request and pass an existing agent_session_id when available. Tool-result boundary: do not claim a session was found, rebound, closed, or inspected until agent_session returns that result; before the call, say what you are checking or changing, and after the call report only confirmed ids, bindings, and status fields. ID carry-forward: every multi-step session/project workflow must copy the returned agent_session_id and, when present, project_id / session_binding.project_id into later calls. Do not rely on the natural-language project title after a list/status/switch result gives you a stable id. If agent_session exposes API friction, unexpected response shapes, unclear session/project binding, a bug, or user frustration, call super_carl_action with action_id="report_feedback"; report_feedback is non-mutating and does not require user confirmation. mode="start" also returns an orientation block — when orientation.is_first_time is true (or active_project_count is 0), follow the orientation.suggested_topics list and call get_product_help for each before describing Super Carl or running broad searches, so you orient the user in current product vocabulary (the unit of work is a "project") instead of improvising. Use mode="list" when the user wants to resume or check in on an older session. Pass search for natural references such as "Claude", "AI founders", or "recruiter outreach"; results are ordered by most recent activity, so "my Claude session" normally means list with search="Claude" and use the latest clear match. If multiple plausible sessions/projects remain, ask the user to choose before mutating state. Use mode="status" to inspect the active project; its delivery_stall / linkedin_delivery fields distinguish LinkedIn daily-50 cap waits (linkedin_daily_dm_limit_reached, auto-resume/scheduled) from non-limit LinkedIn failures that may need user-confirmed retry. Use mode="switch_project" to point an existing session at a specific project so later session-aware calls can omit project_id. Use the returned agent_session_id as the canonical session id.
company_search
ChatGPTUse company_search for company-first or ambiguity-sensitive work. Use it when the user asks for company rows/counts/research, when a named employer is ambiguous/unresolved and you need candidates for clarification, when a long or messy named-company list needs identity resolution, when a verified current roster/spreadsheet/exclusion-sensitive workflow spans many employers, when the input is a domain/LinkedIn company URL, when per-company resolution evidence matters, or when a company cohort is defined by attributes such as funding, size, industry, growth, technology, location, stalled/acquired status, or similar-company logic. Do NOT call company_search just because the user asks for a common named employer in a people request such as "people I know at Acme Corp"; use people_search direct filters like filters.companies.include:["Acme Corp"] for common named employers. Never put a company only in people_search.query; broad text ranking can return recruiters/sales who mention the brand instead of employees. Simple company_search contract. Use query for one named company/brand/domain/LinkedIn URL or loose company-name text. Use filters.company_search.include.filters / filters.company_search.exclude.filters for company attributes and omit query unless a company name/theme keyword is still needed. These are company filters only: person requirements such as job titles, skills, years of experience, connection degree, or person location belong in the downstream people_search binding. Disambiguation handoff. When company_search is needed, step 1: call company_search with {"query":"Acme Corp","resolve_only":true}. Step 2: inspect the literal company_resolution.status field and branch on it. If company_resolution.status === "resolved", run the returned recommended_next_call / required_next_call, or call people_search with {"preview":true,"filters":{"companies":{"include":["<selected company id or name>"],"include_current_only":true}}}. If company_resolution.status === "set", use filters.companies.include_company_search_id:"<search_id>". If status is ambiguous or unresolved, ask for a domain or LinkedIn company URL before binding. Do NOT put the resolved brand back into people_search.query; this is filters mode, so add roles like engineers/product as filters.job_titles, locations as filters.locations, and "I know" / "in my network" as filters.connection_degrees:["1st"] while preserving filters.companies. Current vs alumni/former employees. Default downstream people binding is current-employer (people_search_scope:"current", filters.companies.include_current_only:true). For alumni, former employees, "previously worked at", "experience at", or "any experience" requests, set people_search_scope:"any_experience" on this company_search call; the returned people_search_binding / recommended_next_call / required_next_call will use include_current_only:false so people_search matches prior companies too. Lists. For many explicit company names, use company_search_batch when available instead of serial single-company calls; it resolves each name and returns aggregate people_search next_actions and a top-level recommended_next_call. If the available MCP tool list only exposes company_search, make one resolve_only:true call per company, inspect every company_resolution.status, ask once for unresolved/ambiguous names, then run people_search with concrete resolved bindings: filters.companies.include:[<resolved company names or ids>] and include_current_only:true for current rosters. Do not put prose like "at the resolved companies" in top-level people_search.query. Modes. resolve_only: true (cheapest — only company_resolution + search_id; use for named-company disambiguation passes, precise roster/warm-path setup, or batch identity checks, not for ordinary common-employer people searches); preview: true (default — fast count + search_id + trimmed companies[] rows); preview: false (full detail rows; use only after filters are …
company_search
ChatGPTUse company_search for company-first or ambiguity-sensitive work. Use it when the user asks for company rows/counts/research, when a named employer is ambiguous/unresolved and you need candidates for clarification, when a long or messy named-company list needs identity resolution, when a verified current roster/spreadsheet/exclusion-sensitive workflow spans many employers, when the input is a domain/LinkedIn company URL, when per-company resolution evidence matters, or when a company cohort is defined by attributes such as funding, size, industry, growth, technology, location, stalled/acquired status, or similar-company logic. Do NOT call company_search just because the user asks for a common named employer in a people request such as "people I know at Acme Corp"; use people_search direct filters like filters.companies.include:["Acme Corp"] for common named employers. Never put a company only in people_search.query; broad text ranking can return recruiters/sales who mention the brand instead of employees. Simple company_search contract. Use query for one named company/brand/domain/LinkedIn URL or loose company-name text. Use filters.company_search.include.filters / filters.company_search.exclude.filters for company attributes and omit query unless a company name/theme keyword is still needed. These are company filters only: person requirements such as job titles, skills, years of experience, connection degree, or person location belong in the downstream people_search binding. Disambiguation handoff. When company_search is needed, step 1: call company_search with {"query":"Acme Corp","resolve_only":true}. Step 2: inspect the literal company_resolution.status field and branch on it. If company_resolution.status === "resolved", run the returned recommended_next_call / required_next_call, or call people_search with {"preview":true,"filters":{"companies":{"include":["<selected company id or name>"],"include_current_only":true}}}. If company_resolution.status === "set", use filters.companies.include_company_search_id:"<search_id>". If status is ambiguous or unresolved, ask for a domain or LinkedIn company URL before binding. Do NOT put the resolved brand back into people_search.query; this is filters mode, so add roles like engineers/product as filters.job_titles, locations as filters.locations, and "I know" / "in my network" as filters.connection_degrees:["1st"] while preserving filters.companies. Current vs alumni/former employees. Default downstream people binding is current-employer (people_search_scope:"current", filters.companies.include_current_only:true). For alumni, former employees, "previously worked at", "experience at", or "any experience" requests, set people_search_scope:"any_experience" on this company_search call; the returned people_search_binding / recommended_next_call / required_next_call will use include_current_only:false so people_search matches prior companies too. Lists. For many explicit company names, use company_search_batch when available instead of serial single-company calls; it resolves each name and returns aggregate people_search next_actions and a top-level recommended_next_call. If the available MCP tool list only exposes company_search, make one resolve_only:true call per company, inspect every company_resolution.status, ask once for unresolved/ambiguous names, then run people_search with concrete resolved bindings: filters.companies.include:[<resolved company names or ids>] and include_current_only:true for current rosters. Do not put prose like "at the resolved companies" in top-level people_search.query. Modes. resolve_only: true (cheapest — only company_resolution + search_id; use for named-company disambiguation passes, precise roster/warm-path setup, or batch identity checks, not for ordinary common-employer people searches); preview: true (default — fast count + search_id + trimmed companies[] rows); preview: false (full detail rows; use only after filters are …
company_search_batch
ChatGPTBatch named-company resolution for long research prompts. Use this before people_search when the user gives a list of companies. Each item runs the same cheap company_search resolve_only path and returns per-row company_resolution, search_id, next_actions, and people_search_binding when bindable. If at least one company resolves, the top-level recommended_next_call and required_next_call are complete ready-to-run { tool:"people_search", args:{...} } aggregate searches across resolved companies; execute one directly or add extra title/location/network filters while preserving filters.companies and avoiding a top-level people_search query. The top-level next_actions[] also includes an aggregate people_search.search_resolved_companies action for broad sweeps plus people_search.iterate_per_company when per-company coverage matters. This tool defaults to response_verbosity:"minimal" for bounded-context MCP clients: it drops duplicated per-row next_actions while preserving each row's resolution state, search_id, and people_search_binding plus the aggregate top-level next calls. Set response_verbosity:"compact" only when you want results[] plus aggregate counts and will handle follow-up calls yourself. Set response_verbosity:"detailed" only when debugging per-row resolver actions. For alumni/former/previous-company lists, set people_search_scope:"any_experience" so returned people_search bindings use filters.companies.include_current_only:false. Example: {"companies":["Hinge","Bumble","DoorDash"],"people_search_scope":"any_experience"} then run recommended_next_call and add NYC/title filters as needed. Ask the user once for domains or LinkedIn company URLs when rows are ambiguous or unresolved. Session tracking: pass agent_session_id from agent_session.start/list when you have one. Calls without a session are automatically grouped into an implicit Super Carl MCP session for this caller/client so the activity can appear on Home.
company_search_batch
ChatGPTBatch named-company resolution for long research prompts. Use this before people_search when the user gives a list of companies. Each item runs the same cheap company_search resolve_only path and returns per-row company_resolution, search_id, next_actions, and people_search_binding when bindable. If at least one company resolves, the top-level recommended_next_call and required_next_call are complete ready-to-run { tool:"people_search", args:{...} } aggregate searches across resolved companies; execute one directly or add extra title/location/network filters while preserving filters.companies and avoiding a top-level people_search query. The top-level next_actions[] also includes an aggregate people_search.search_resolved_companies action for broad sweeps plus people_search.iterate_per_company when per-company coverage matters. This tool defaults to response_verbosity:"minimal" for bounded-context MCP clients: it drops duplicated per-row next_actions while preserving each row's resolution state, search_id, and people_search_binding plus the aggregate top-level next calls. Set response_verbosity:"compact" only when you want results[] plus aggregate counts and will handle follow-up calls yourself. Set response_verbosity:"detailed" only when debugging per-row resolver actions. For alumni/former/previous-company lists, set people_search_scope:"any_experience" so returned people_search bindings use filters.companies.include_current_only:false. Example: {"companies":["Hinge","Bumble","DoorDash"],"people_search_scope":"any_experience"} then run recommended_next_call and add NYC/title filters as needed. Ask the user once for domains or LinkedIn company URLs when rows are ambiguous or unresolved. Session tracking: pass agent_session_id from agent_session.start/list when you have one. Calls without a session are automatically grouped into an implicit Super Carl MCP session for this caller/client so the activity can appear on Home.
get_product_help
ChatGPTFetch the canonical product-help topic for a Super Carl feature (UI nav, product overview/how Carl works, settings location, integration setup, sync diagnostics, social-proximity scoring, relationship signals, or warm-intro paths). Call with topic="index" to discover available topic ids; call with a specific topic id to get the topic markdown PLUS the current user's live state (LinkedIn session, Gmail/Calendar/Slack/X/IG accounts, notification toggles, timezone, plan tier, availability windows) where applicable, plus an external docs URL when one exists. Call this BEFORE describing any Super Carl UI or behavior, or answering product overview questions like "What do you do?", "What is Super Carl?", "How do you work?", or "Why can Carl find people no one else can?" — never improvise screen names, button labels, or feature availability. If your first topic guess is wrong, call again with topic="index" or another id. If get_product_help reveals product-doc friction, missing docs, unexpected response shapes, a bug, or user frustration, call super_carl_action with action_id="report_feedback"; report_feedback is non-mutating and does not require user confirmation.
get_product_help
ChatGPTFetch the canonical product-help topic for a Super Carl feature (UI nav, product overview/how Carl works, settings location, integration setup, sync diagnostics, social-proximity scoring, relationship signals, or warm-intro paths). Call with topic="index" to discover available topic ids; call with a specific topic id to get the topic markdown PLUS the current user's live state (LinkedIn session, Gmail/Calendar/Slack/X/IG accounts, notification toggles, timezone, plan tier, availability windows) where applicable, plus an external docs URL when one exists. Call this BEFORE describing any Super Carl UI or behavior, or answering product overview questions like "What do you do?", "What is Super Carl?", "How do you work?", or "Why can Carl find people no one else can?" — never improvise screen names, button labels, or feature availability. If your first topic guess is wrong, call again with topic="index" or another id. If get_product_help reveals product-doc friction, missing docs, unexpected response shapes, a bug, or user frustration, call super_carl_action with action_id="report_feedback"; report_feedback is non-mutating and does not require user confirmation.
jobs_search
ChatGPTMost jobs_search calls feed a downstream people_search — the goal is usually "find roles → find a warm path in." Natural-language job search scored against the viewer's social-graph overlay. Each result is decorated with a network block summarizing 1st/2nd-degree connections the viewer has at the posting's company. Default with_people: false returns job rows (title, company, network block); set with_people: true to inline 1st/2nd-degree people at each hiring company in one round-trip (the "map a job to a path in" shape, no follow-up call needed). Composes with the people-search four-phase flow (see people_search). When a job's hiring employer matters, next_actions[] will surface a people_search.bind_job_company entry whose args_diff patches the right hiring-company filter into a follow-up people_search, and may also surface company_search.resolve_employer for canonical brand resolution first. If a hiring-company-bound people search returns zero, report that there is no warm path in the live data; do not recover with broad unbound people_search. Accepts the same filters.hiring.* / company_stage shape as the web app. Pass delegate_user_id to search as a permitted teammate. Session tracking: pass agent_session_id from agent_session.start/list when you have one. Calls without a session are automatically grouped into an implicit Super Carl MCP session for this caller/client so the activity can appear on Home.
jobs_search
ChatGPTMost jobs_search calls feed a downstream people_search — the goal is usually "find roles → find a warm path in." Natural-language job search scored against the viewer's social-graph overlay. Each result is decorated with a network block summarizing 1st/2nd-degree connections the viewer has at the posting's company. Default with_people: false returns job rows (title, company, network block); set with_people: true to inline 1st/2nd-degree people at each hiring company in one round-trip (the "map a job to a path in" shape, no follow-up call needed). Composes with the people-search four-phase flow (see people_search). When a job's hiring employer matters, next_actions[] will surface a people_search.bind_job_company entry whose args_diff patches the right hiring-company filter into a follow-up people_search, and may also surface company_search.resolve_employer for canonical brand resolution first. If a hiring-company-bound people search returns zero, report that there is no warm path in the live data; do not recover with broad unbound people_search. Accepts the same filters.hiring.* / company_stage shape as the web app. Pass delegate_user_id to search as a permitted teammate. Session tracking: pass agent_session_id from agent_session.start/list when you have one. Calls without a session are automatically grouped into an implicit Super Carl MCP session for this caller/client so the activity can appear on Home.
people_lookup_batch
ChatGPTBatch direct LinkedIn profile loading. This is not a verifier or certification step; it calls the same direct people lookup path as people_search for each LinkedIn profile URL or vanity and returns the latest available Super Carl profile data. Use it when an agent has a spreadsheet/list of known LinkedIn identities and wants fuller profile rows without repeating single-tool calls. Each profile may spend a LinkedIn lookup credit if it is not already cached/enriched. Accepts linkedin_profile_url, linkedin_url, or linkedin_username per item. Results are returned per input row with status_code, users, and search_metadata. Evidence options mirror people_search: text is compact; JSON is more verbose when the caller wants to inspect profile fields. For roster QA or current-title/current-company alignment, request evidence_format: "json" or "both" (or include_evidence_json: true); a lookup without evidence only hydrates identity/profile data and is not enough to inspect alignment. When the user asks to "verify" profiles, say plainly that this loads latest available Super Carl profile/evidence and reports per-row status, but it cannot certify identity or employment and not_found / wrong-person rows must be reported or replaced via a new company-bound search. Do not describe this tool as verifying or confirming employment. Normal people_search rows with evidence_format: "json" or "both" carry the declarative alignment evidence for current-company/current-title searches; evidence_format:"reasons" is a review-tier narrative mode and is not enough for roster QA/alignment replacement passes. Rows without a LinkedIn identity cannot be batch-loaded; if you need to recover or replace those candidates, restart from company_search and then people_search with resolver-backed company binding plus filters.companies.include_current_only: true, filters.job_titles.current_only: true, and evidence_format:"json" or "both". Do not fall back to broad keyword-only people_search for unresolved rows. Session tracking: pass agent_session_id from agent_session.start/list when you have one. Calls without a session are automatically grouped into an implicit Super Carl MCP session for this caller/client so the activity can appear on Home.
people_lookup_batch
ChatGPTBatch direct LinkedIn profile loading. This is not a verifier or certification step; it calls the same direct people lookup path as people_search for each LinkedIn profile URL or vanity and returns the latest available Super Carl profile data. Use it when an agent has a spreadsheet/list of known LinkedIn identities and wants fuller profile rows without repeating single-tool calls. Each profile may spend a LinkedIn lookup credit if it is not already cached/enriched. Accepts linkedin_profile_url, linkedin_url, or linkedin_username per item. Results are returned per input row with status_code, users, and search_metadata. Evidence options mirror people_search: text is compact; JSON is more verbose when the caller wants to inspect profile fields. For roster QA or current-title/current-company alignment, request evidence_format: "json" or "both" (or include_evidence_json: true); a lookup without evidence only hydrates identity/profile data and is not enough to inspect alignment. When the user asks to "verify" profiles, say plainly that this loads latest available Super Carl profile/evidence and reports per-row status, but it cannot certify identity or employment and not_found / wrong-person rows must be reported or replaced via a new company-bound search. Do not describe this tool as verifying or confirming employment. Normal people_search rows with evidence_format: "json" or "both" carry the declarative alignment evidence for current-company/current-title searches; evidence_format:"reasons" is a review-tier narrative mode and is not enough for roster QA/alignment replacement passes. Rows without a LinkedIn identity cannot be batch-loaded; if you need to recover or replace those candidates, restart from company_search and then people_search with resolver-backed company binding plus filters.companies.include_current_only: true, filters.job_titles.current_only: true, and evidence_format:"json" or "both". Do not fall back to broad keyword-only people_search for unresolved rows. Session tracking: pass agent_session_id from agent_session.start/list when you have one. Calls without a session are automatically grouped into an implicit Super Carl MCP session for this caller/client so the activity can appear on Home.
people_search
ChatGPTDefault for person discovery. Use people_search first for "who should I talk to", "who in my network", "people with experience/expertise in X", advisor/warm-intro/referral questions, and broad role/industry/company-background searches. This remains true when the user's topic could appear in posts. Use posts_search first only when the user's explicit anchor is post/activity behavior such as posting, liking, commenting, resharing, engagement counts, hashtags, or posts mentioning a target. Four-phase flow. Follow next_actions[] on every response — the structured pointers tell you the next call. Exception: people_search.next_page is user opt-in pagination, not an automatic continuation; fetch the next page only when the user asks to see more results, asks for a deeper review, or explicitly requests a bulk/rank export. Phases: 1. Bind named employers directly when unambiguous. If the user asks for people at/from a common, clearly identifiable company name, filters mode with filters.companies.include:["Acme Corp"] is valid. Use include_current_only:true for current employees, include_current_only:false for alumni/former/any-experience, and filters.connection_degrees:["1st"] for "people I know". Use company_search first only when the company name is ambiguous/unresolved, a long/messy list needs resolution, the input is a domain/LinkedIn company URL, the user asked for company rows/counts, or the employer cohort is defined by attributes such as funding, size, industry, growth, or similar companies. 2. Iterate filters cheaply with preview: true — returns count + filter warnings, NO users[], no LLM by default. Send NL query verbatim on the FIRST preview pass so the server's translation pipeline gets to do its job. If you must pin hard constraints on that same first pass, use filter_updates with canonical AdvancedFilters keys. Do not pre-translate semantic criteria such as title families, AI/product/domain expertise, qualitative company descriptors, or inferred company size into filter_updates; let the translator take the first shot. Do not hand-author filters for initial NL searches. For bulk rank/page exports, keep preview:true and add include_preview_rows:true, evidence_format:"none", response_verbosity:"minimal", skip_match_reasons:true. 3. Review candidates with preview: false, evidence_format: "reasons", limit: 25 — 25 thin rows + LLM-built match_reasons[] per row. This is the canonical narrative review tier for ranked people, warm paths, "why", and shortlist answers; do not skip it or jump straight from preview to deep-dive evidence when the user expects named people with reasons. For roster QA, current-company/current-title alignment, spreadsheet enrichment, or replacement rows after bad LinkedIn lookups, use evidence_format:"json" or "both" instead of "reasons" so declarative profile fields are available. 4. Deep dive when reasons look promising: same filters with evidence_format: "text" (raw profile prose) for ranking, or people_lookup_batch with the row's linkedin_url for full structured detail. Carrying filters across phases. After Phase 2's preview: true returns, search_metadata.filters.advanced holds the server-resolved AdvancedFilters object the translator produced from your NL query (this includes role/title, location, employer, years-experience, network, company_size, companies.include_company_search_id, locations.exclude, etc.). For Phase 3 / Phase 4, pass the entire object as `filters` in subsequent calls — preserve it wholesale unless you are explicitly adding, removing, or tightening a constraint for the user. Do not reconstruct a partial subset: dropping translated title, network, location, company, or tenure fields changes the search. It's fine (and expected) to add, drop, or tighten fields as the conversation evolves; what's NOT fine is silently dropping fields by re-translating the same query at preview: false. The LLM filter translator is non-deterministic across calls, so re-running the same NL on the ful…
people_search
ChatGPTDefault for person discovery. Use people_search first for "who should I talk to", "who in my network", "people with experience/expertise in X", advisor/warm-intro/referral questions, and broad role/industry/company-background searches. This remains true when the user's topic could appear in posts. Use posts_search first only when the user's explicit anchor is post/activity behavior such as posting, liking, commenting, resharing, engagement counts, hashtags, or posts mentioning a target. Four-phase flow. Follow next_actions[] on every response — the structured pointers tell you the next call. Exception: people_search.next_page is user opt-in pagination, not an automatic continuation; fetch the next page only when the user asks to see more results, asks for a deeper review, or explicitly requests a bulk/rank export. Phases: 1. Bind named employers directly when unambiguous. If the user asks for people at/from a common, clearly identifiable company name, filters mode with filters.companies.include:["Acme Corp"] is valid. Use include_current_only:true for current employees, include_current_only:false for alumni/former/any-experience, and filters.connection_degrees:["1st"] for "people I know". Use company_search first only when the company name is ambiguous/unresolved, a long/messy list needs resolution, the input is a domain/LinkedIn company URL, the user asked for company rows/counts, or the employer cohort is defined by attributes such as funding, size, industry, growth, or similar companies. 2. Iterate filters cheaply with preview: true — returns count + filter warnings, NO users[], no LLM by default. Send NL query verbatim on the FIRST preview pass so the server's translation pipeline gets to do its job. If you must pin hard constraints on that same first pass, use filter_updates with canonical AdvancedFilters keys. Do not pre-translate semantic criteria such as title families, AI/product/domain expertise, qualitative company descriptors, or inferred company size into filter_updates; let the translator take the first shot. Do not hand-author filters for initial NL searches. For bulk rank/page exports, keep preview:true and add include_preview_rows:true, evidence_format:"none", response_verbosity:"minimal", skip_match_reasons:true. 3. Review candidates with preview: false, evidence_format: "reasons", limit: 25 — 25 thin rows + LLM-built match_reasons[] per row. This is the canonical narrative review tier for ranked people, warm paths, "why", and shortlist answers; do not skip it or jump straight from preview to deep-dive evidence when the user expects named people with reasons. For roster QA, current-company/current-title alignment, spreadsheet enrichment, or replacement rows after bad LinkedIn lookups, use evidence_format:"json" or "both" instead of "reasons" so declarative profile fields are available. 4. Deep dive when reasons look promising: same filters with evidence_format: "text" (raw profile prose) for ranking, or people_lookup_batch with the row's linkedin_url for full structured detail. Carrying filters across phases. After Phase 2's preview: true returns, search_metadata.filters.advanced holds the server-resolved AdvancedFilters object the translator produced from your NL query (this includes role/title, location, employer, years-experience, network, company_size, companies.include_company_search_id, locations.exclude, etc.). For Phase 3 / Phase 4, pass the entire object as `filters` in subsequent calls — preserve it wholesale unless you are explicitly adding, removing, or tightening a constraint for the user. Do not reconstruct a partial subset: dropping translated title, network, location, company, or tenure fields changes the search. It's fine (and expected) to add, drop, or tighten fields as the conversation evolves; what's NOT fine is silently dropping fields by re-translating the same query at preview: false. The LLM filter translator is non-deterministic across calls, so re-running the same NL on the ful…
posts_search
ChatGPTUse posts_search for post-first questions. This is the direct search surface for LinkedIn/public activity rows: authored posts, reposts/reshares, comments, likes/reactions, target-company mentions, hashtags, and engagement counts. Use it before people_search when the user's anchor is something someone posted, liked, commented on, or reshared — for example "who in my network has been posting about hiring", "people with posts over 10 likes last week", or "who liked/commented on competitor posts". Do not use for broad people discovery. Requests like "who should I talk to", "who in my network has experience in X", "people relevant to my new role at X", "why now for these people", or "find advisors/referrals in an industry" are people_search questions unless the user explicitly asks about posts/activity. For "who should I talk to about my new role at Acme Corp in consumer travel", call people_search with that person-discovery intent; do not start with posts_search just because consumer-travel posts might exist. For broad timing/ranking rationale, use people_search with evidence_text_mode:"full" and select:["recency_evidence"] first; use posts_search only as supplemental post/activity evidence after the candidate set is narrowed. Post rows vs people pivot. Default with_people:false returns matching post/activity rows. Set with_people:true when the user's goal is people discovery: the REST response includes a deduped people[] set derived from matching actors/authors plus compact matched-post evidence. Every response also includes people_search_binding and MCP next_actions[]; follow people_search.from_posts when you need the full profile-search stack, relationship detail, match reasons, additional role/location/company/network filters, pagination, or project/outreach follow-up. Simple posts_search contract. Keep post/activity constraints in filters.posts. Do not put profile constraints there: job titles, employers, person locations, network degree, years of experience, and relationship detail belong in the follow-up people_search call created from people_search_binding. Structured filters. Put post constraints under filters.posts: mentioned is the hard/literal field for "posts mentioning X" or "posts containing X". For softer topic intent like "who in my network is hiring" or "posting about hiring", use additional_context_keywords_core and additional_context_keywords_supporting with keyword_match_mode:"soft" instead of mentioned; core is sparse/high-signal and supporting broadens recall, mirroring people_search additional-context keyword conventions. Other fields: action_types for ["post","repost","comment","like","reaction"], min_reactions, min_comments, min_engagement, published_within_days, published_after, published_before, target_companies, target_people, and target_urls. For "more than 10 likes" use min_reactions:11. For "last week" use published_within_days:7. For competitor engagement, resolve named competitors with company_search / company_search_batch when ambiguity matters, then pass names/ids/URLs in filters.posts.target_companies and set action_types:["like","comment","repost"] as appropriate. Composing with people_search. posts_search answers "which posts match?" and can produce a quick deduped actor set. people_search answers "which profiles match this post behavior plus other constraints?" To map a post query into people, execute the returned people_search_binding or call people_search with filters.posts copied exactly, then add network filters (connection_degrees:["1st"], network_filter_mode:"filter"), titles, locations, company filters, evidence_format, or relationship_detail structurally. Preserve every non-post requirement from the user's brief during the people_search pivot: "in my network" / "people I know" means add a concrete network filter such as filters.connection_degrees:["1st"] (or the requested 1st/2nd-degree set); titles, locations, employers, and seniority must also stay structured instead of be…
posts_search
ChatGPTUse posts_search for post-first questions. This is the direct search surface for LinkedIn/public activity rows: authored posts, reposts/reshares, comments, likes/reactions, target-company mentions, hashtags, and engagement counts. Use it before people_search when the user's anchor is something someone posted, liked, commented on, or reshared — for example "who in my network has been posting about hiring", "people with posts over 10 likes last week", or "who liked/commented on competitor posts". Do not use for broad people discovery. Requests like "who should I talk to", "who in my network has experience in X", "people relevant to my new role at X", "why now for these people", or "find advisors/referrals in an industry" are people_search questions unless the user explicitly asks about posts/activity. For "who should I talk to about my new role at Acme Corp in consumer travel", call people_search with that person-discovery intent; do not start with posts_search just because consumer-travel posts might exist. For broad timing/ranking rationale, use people_search with evidence_text_mode:"full" and select:["recency_evidence"] first; use posts_search only as supplemental post/activity evidence after the candidate set is narrowed. Post rows vs people pivot. Default with_people:false returns matching post/activity rows. Set with_people:true when the user's goal is people discovery: the REST response includes a deduped people[] set derived from matching actors/authors plus compact matched-post evidence. Every response also includes people_search_binding and MCP next_actions[]; follow people_search.from_posts when you need the full profile-search stack, relationship detail, match reasons, additional role/location/company/network filters, pagination, or project/outreach follow-up. Simple posts_search contract. Keep post/activity constraints in filters.posts. Do not put profile constraints there: job titles, employers, person locations, network degree, years of experience, and relationship detail belong in the follow-up people_search call created from people_search_binding. Structured filters. Put post constraints under filters.posts: mentioned is the hard/literal field for "posts mentioning X" or "posts containing X". For softer topic intent like "who in my network is hiring" or "posting about hiring", use additional_context_keywords_core and additional_context_keywords_supporting with keyword_match_mode:"soft" instead of mentioned; core is sparse/high-signal and supporting broadens recall, mirroring people_search additional-context keyword conventions. Other fields: action_types for ["post","repost","comment","like","reaction"], min_reactions, min_comments, min_engagement, published_within_days, published_after, published_before, target_companies, target_people, and target_urls. For "more than 10 likes" use min_reactions:11. For "last week" use published_within_days:7. For competitor engagement, resolve named competitors with company_search / company_search_batch when ambiguity matters, then pass names/ids/URLs in filters.posts.target_companies and set action_types:["like","comment","repost"] as appropriate. Composing with people_search. posts_search answers "which posts match?" and can produce a quick deduped actor set. people_search answers "which profiles match this post behavior plus other constraints?" To map a post query into people, execute the returned people_search_binding or call people_search with filters.posts copied exactly, then add network filters (connection_degrees:["1st"], network_filter_mode:"filter"), titles, locations, company filters, evidence_format, or relationship_detail structurally. Preserve every non-post requirement from the user's brief during the people_search pivot: "in my network" / "people I know" means add a concrete network filter such as filters.connection_degrees:["1st"] (or the requested 1st/2nd-degree set); titles, locations, employers, and seniority must also stay structured instead of be…
project_action
ChatGPTPolymorphic project tool for the same project APIs exposed in Super Carl product flows. Pass mode to choose the operation: Tool-result boundary: plan and speak in future/progress tense until a project_action response returns success or the requested read data. Do not tell the user a project was renamed, targets were added, drafts were saved, delivery was activated, or status/counts were found before the corresponding tool result exists; after the call, report only what the tool confirmed. ID carry-forward: after mode="list", mode="status", or agent_session returns a stable project_id, pass that exact project_id into later project_action calls such as status, targets, rename, metrics, update_message, or activate. If you are working inside an MCP session with a returned agent_session_id, pass that agent_session_id on every related project_action call; when the session is bound, project_id may be omitted and the binding is used. Never substitute project titles, company names, search ids, or display labels for ids. Feedback reporting: if project_action exposes API friction, unexpected response shapes, unclear project/session binding, a bug, or user frustration, call super_carl_action with action_id="report_feedback"; report_feedback is non-mutating and does not require user confirmation. CTA policy: When composing outreach, keep the call to action explicit. Use a plain reply CTA for Super Carl/on-platform direct messages; do not include [JoinLink] for those recipients because they are already on-platform. For off-platform Gmail/LinkedIn quick_text outreach, include [JoinLink] when the recipient needs a place to join/respond. Use [SchedulingLink] only when the user asks for calls, booking, scheduling, or engagement_mode="schedule_live". If the user approves sending or activation but the CTA is unclear, ask one concise choice before activate/send. - mode="list" (read-only): List active projects and conversation sessions for the acting user, including search-only drafts and standalone Carl/Claude/MCP conversations that have not become full shortlist projects yet. Use this when an MCP session needs to find the project_id or agent_session_id before inspecting targets or metrics. Pass search to narrow by project title, description, or source conversation/session labels (for example search="Claude" for Claude-originated sessions/projects, or search="AI founders" for matching project titles). Set include_archived:true to include archived rows, or archived:true / archived:false for archived-only / active-only. When agent_session_id is bound to a project, the response includes current_session_project / current_session_project_id even if that project would otherwise be hidden by generic list filters such as archived status. - mode="status" (read-only): Fetch one project by project_id. If the caller passes agent_session_id and the session is already bound to a project, project_id can be omitted. - mode="targets" (read-only): List active included project targets (the user-facing project shortlist), with outreach status, reachability, correspondence summary, and pagination. For email/Gmail targets each row includes delivery_preview { subject, body } — the EXACT email subject and final link-expanded body the recipient will receive. Always show the user this delivery_preview.subject (not just the message body) before any send/activate so the subject is never sent unseen; the body in delivery_preview already has links resolved and is the canonical send copy. outreach_status meanings: "pending" = drafted/awaiting send; "queued_send" = the user already queued THIS single target for immediate delivery (e.g. via the app "Send now" action) and it is in flight — treat it like "sending": do not draft or send to it again, do not include it in a bulk activate, and poll/report rather than re-deliver. "sending" = actively delivering; "contacted"/"referral_contacted" = already delivered; "failed"/"daily_limit_reached" = see the daily-cap note below. - mode="recipient_emails" (read-mostly): Resolve selectable Gmail rec…
project_action
ChatGPTPolymorphic project tool for the same project APIs exposed in Super Carl product flows. Pass mode to choose the operation: Tool-result boundary: plan and speak in future/progress tense until a project_action response returns success or the requested read data. Do not tell the user a project was renamed, targets were added, drafts were saved, delivery was activated, or status/counts were found before the corresponding tool result exists; after the call, report only what the tool confirmed. ID carry-forward: after mode="list", mode="status", or agent_session returns a stable project_id, pass that exact project_id into later project_action calls such as status, targets, rename, metrics, update_message, or activate. If you are working inside an MCP session with a returned agent_session_id, pass that agent_session_id on every related project_action call; when the session is bound, project_id may be omitted and the binding is used. Never substitute project titles, company names, search ids, or display labels for ids. Feedback reporting: if project_action exposes API friction, unexpected response shapes, unclear project/session binding, a bug, or user frustration, call super_carl_action with action_id="report_feedback"; report_feedback is non-mutating and does not require user confirmation. CTA policy: When composing outreach, keep the call to action explicit. Use a plain reply CTA for Super Carl/on-platform direct messages; do not include [JoinLink] for those recipients because they are already on-platform. For off-platform Gmail/LinkedIn quick_text outreach, include [JoinLink] when the recipient needs a place to join/respond. Use [SchedulingLink] only when the user asks for calls, booking, scheduling, or engagement_mode="schedule_live". If the user approves sending or activation but the CTA is unclear, ask one concise choice before activate/send. - mode="list" (read-only): List active projects and conversation sessions for the acting user, including search-only drafts and standalone Carl/Claude/MCP conversations that have not become full shortlist projects yet. Use this when an MCP session needs to find the project_id or agent_session_id before inspecting targets or metrics. Pass search to narrow by project title, description, or source conversation/session labels (for example search="Claude" for Claude-originated sessions/projects, or search="AI founders" for matching project titles). Set include_archived:true to include archived rows, or archived:true / archived:false for archived-only / active-only. When agent_session_id is bound to a project, the response includes current_session_project / current_session_project_id even if that project would otherwise be hidden by generic list filters such as archived status. - mode="status" (read-only): Fetch one project by project_id. If the caller passes agent_session_id and the session is already bound to a project, project_id can be omitted. - mode="targets" (read-only): List active included project targets (the user-facing project shortlist), with outreach status, reachability, correspondence summary, and pagination. For email/Gmail targets each row includes delivery_preview { subject, body } — the EXACT email subject and final link-expanded body the recipient will receive. Always show the user this delivery_preview.subject (not just the message body) before any send/activate so the subject is never sent unseen; the body in delivery_preview already has links resolved and is the canonical send copy. outreach_status meanings: "pending" = drafted/awaiting send; "queued_send" = the user already queued THIS single target for immediate delivery (e.g. via the app "Send now" action) and it is in flight — treat it like "sending": do not draft or send to it again, do not include it in a bulk activate, and poll/report rather than re-deliver. "sending" = actively delivering; "contacted"/"referral_contacted" = already delivered; "failed"/"daily_limit_reached" = see the daily-cap note below. - mode="recipient_emails" (read-mostly): Resolve selectable Gmail rec…
project_google_sheet_sync
ChatGPTCreate, update, inspect, and refresh a Super Carl-owned Google Sheet for a project. The sheet is initially shared with the requesting user primary email as an editor, and editors can reshare it when Google Workspace policy allows. Use this after search/list enrichment, shortlist updates, or outreach draft updates when the user asks to share/update a spreadsheet.
project_google_sheet_sync
ChatGPTCreate, update, inspect, and refresh a Super Carl-owned Google Sheet for a project. The sheet is initially shared with the requesting user primary email as an editor, and editors can reshare it when Google Workspace policy allows. Use this after search/list enrichment, shortlist updates, or outreach draft updates when the user asks to share/update a spreadsheet.
query_search_result
ChatGPTReshape a verbose result you already got from people_search into the exact table the user asked for — pick columns, filter, exclude, sort, paginate — without re-running the search. This is NOT a Super Carl project/assignment tool: do not pass project_id or project_context; it only transforms search rows you already have. In in-product chat, prefer result_ref from the prior search result's navigator_result_ref so the tool can replay rows server-side instead of asking the model to paste a huge JSON array. In MCP, pass rows inline for max fidelity, or pass a prior full people_search search_id/search_cache_key to replay its persisted snapshot. Set columns to the output columns: each is { label, plus either a field path like "current_title", or a named derived resolver: connector_name, is_first_degree, degree_flag, mutual_count, best_path, move_month, firm_and_role, why_now_signal, prior_role, experience_overlap }. Use exclude to drop the viewer (self) and any target subject (e.g. the person being reference-checked) so they never appear as a row. Returns condensed rows plus a cohort_signal ("ok" or "insufficient_cohort") — when it is insufficient_cohort the search did not actually contain the asked-for cohort, so report that honestly instead of presenting the rows as a match.
query_search_result
ChatGPTReshape a verbose result you already got from people_search into the exact table the user asked for — pick columns, filter, exclude, sort, paginate — without re-running the search. This is NOT a Super Carl project/assignment tool: do not pass project_id or project_context; it only transforms search rows you already have. In in-product chat, prefer result_ref from the prior search result's navigator_result_ref so the tool can replay rows server-side instead of asking the model to paste a huge JSON array. In MCP, pass rows inline for max fidelity, or pass a prior full people_search search_id/search_cache_key to replay its persisted snapshot. Set columns to the output columns: each is { label, plus either a field path like "current_title", or a named derived resolver: connector_name, is_first_degree, degree_flag, mutual_count, best_path, move_month, firm_and_role, why_now_signal, prior_role, experience_overlap }. Use exclude to drop the viewer (self) and any target subject (e.g. the person being reference-checked) so they never appear as a row. Returns condensed rows plus a cohort_signal ("ok" or "insufficient_cohort") — when it is insufficient_cohort the search did not actually contain the asked-for cohort, so report that honestly instead of presenting the rows as a match.
send_communication
ChatGPTPolymorphic communication tool. mode is required; choose one explicit operation: Feedback reporting: if send_communication exposes API friction, unexpected response shapes, delivery-status ambiguity, unclear errors, a bug, or user frustration, call super_carl_action with action_id="report_feedback"; report_feedback is non-mutating and does not require user confirmation. - mode="precheck" (read-only unless enrichment is requested): Check whether the acting account can deliver to a target via Super Carl DM / invite / referral, Gmail, LinkedIn, X, or Instagram. Pass target identifiers (project_target_id from project_action.targets, target_user_id, linkedin_profile_url / linkedin_username, x_profile_url / x_username, instagram_profile_url / instagram_username, or recipient_email) and optionally a channels array to narrow the check. For outreach planning, check gmail_send, linkedin_send_message, and supercarl_referral_request together: LinkedIn DM is only sendable for first-degree/direct LinkedIn connections; otherwise use Gmail direct if a confident email is available or supercarl_referral_request when a connector can intro the target. For Gmail targeting, a broad/multi-channel precheck never spends credits: it advertises whether an address is plausibly findable via email_enrichment.email_enrichment_available (with an enrichment_inputs breakdown) so you can offer email as an option for free. When you SELECT email for a target — scope the check to channels:["gmail_send"] — the best address resolves automatically (a paid provider lookup may run; no allow_email_enrichment flag needed), returning email_resolution.recipient_email_options plus email_enrichment status. allow_email_enrichment=true also forces resolution. Prefer scoping to gmail_send (or drafting) over enriching many candidates at once — pay for the few you target, not all you browse. Use one returned recipient_email_options[].email or a valid email address explicitly supplied by the user as recipient_email for mode="draft" or mode="send". Sources are presentation-safe: own synced Gmail is labeled "Synced Gmail"; provider/Gmail-from-other-users evidence is labeled "Sourced provider". - mode="history" (read-only): Read prior visible communication history for this target before drafting/sending. Pass target identifiers and optional history_channel (all, email, super_carl, linkedin, x, instagram), limit (default 12, max 50), and offset. By default this returns cached entries, which can be days or weeks stale; when drafting personalized replies or follow-ups that depend on the latest LinkedIn thread, set history_fresh=true first. That queues a targeted LinkedIn conversation refresh and immediately returns cached history plus refresh run ids/state; the request does not wait for the browser refresh. This can research LinkedIn history by target profile/identity even when no tracked outreach thread exists yet. It uses the same history backing the in-product previous-messages UI and includes assignment outreach, Super Carl chat/invites, LinkedIn, Gmail metadata/API sends, X, and Instagram where available. Before drafting personalized outreach, follow returned next_actions[] to call people_lookup_batch with relationship_detail:"intro_paths" so you can inspect relationship.social_map.entries[] for shared employers, mutual connections, and experience overlap that can anchor the message. - mode="draft" (durable, no delivery): Save a reviewed-later outreach draft for a target in the current MCP agent session. Pass channel + message (and Gmail subject) plus a target identifier. Super Carl creates/binds the session project target, expands [JoinLink] and [SchedulingLink] into the final copy, and returns the stored draft details without sending anything. For supercarl_direct_message/on-platform recipients, use a direct reply CTA and do not include [JoinLink]; for Gmail/LinkedIn, use [JoinLink] for join/respond flows and [SchedulingLink] only for booking/schedule flows. For personalized LinkedIn replies/follow-ups, cal…
send_communication
ChatGPTPolymorphic communication tool. mode is required; choose one explicit operation: Feedback reporting: if send_communication exposes API friction, unexpected response shapes, delivery-status ambiguity, unclear errors, a bug, or user frustration, call super_carl_action with action_id="report_feedback"; report_feedback is non-mutating and does not require user confirmation. - mode="precheck" (read-only unless enrichment is requested): Check whether the acting account can deliver to a target via Super Carl DM / invite / referral, Gmail, LinkedIn, X, or Instagram. Pass target identifiers (project_target_id from project_action.targets, target_user_id, linkedin_profile_url / linkedin_username, x_profile_url / x_username, instagram_profile_url / instagram_username, or recipient_email) and optionally a channels array to narrow the check. For outreach planning, check gmail_send, linkedin_send_message, and supercarl_referral_request together: LinkedIn DM is only sendable for first-degree/direct LinkedIn connections; otherwise use Gmail direct if a confident email is available or supercarl_referral_request when a connector can intro the target. For Gmail targeting, a broad/multi-channel precheck never spends credits: it advertises whether an address is plausibly findable via email_enrichment.email_enrichment_available (with an enrichment_inputs breakdown) so you can offer email as an option for free. When you SELECT email for a target — scope the check to channels:["gmail_send"] — the best address resolves automatically (a paid provider lookup may run; no allow_email_enrichment flag needed), returning email_resolution.recipient_email_options plus email_enrichment status. allow_email_enrichment=true also forces resolution. Prefer scoping to gmail_send (or drafting) over enriching many candidates at once — pay for the few you target, not all you browse. Use one returned recipient_email_options[].email or a valid email address explicitly supplied by the user as recipient_email for mode="draft" or mode="send". Sources are presentation-safe: own synced Gmail is labeled "Synced Gmail"; provider/Gmail-from-other-users evidence is labeled "Sourced provider". - mode="history" (read-only): Read prior visible communication history for this target before drafting/sending. Pass target identifiers and optional history_channel (all, email, super_carl, linkedin, x, instagram), limit (default 12, max 50), and offset. By default this returns cached entries, which can be days or weeks stale; when drafting personalized replies or follow-ups that depend on the latest LinkedIn thread, set history_fresh=true first. That queues a targeted LinkedIn conversation refresh and immediately returns cached history plus refresh run ids/state; the request does not wait for the browser refresh. This can research LinkedIn history by target profile/identity even when no tracked outreach thread exists yet. It uses the same history backing the in-product previous-messages UI and includes assignment outreach, Super Carl chat/invites, LinkedIn, Gmail metadata/API sends, X, and Instagram where available. Before drafting personalized outreach, follow returned next_actions[] to call people_lookup_batch with relationship_detail:"intro_paths" so you can inspect relationship.social_map.entries[] for shared employers, mutual connections, and experience overlap that can anchor the message. - mode="draft" (durable, no delivery): Save a reviewed-later outreach draft for a target in the current MCP agent session. Pass channel + message (and Gmail subject) plus a target identifier. Super Carl creates/binds the session project target, expands [JoinLink] and [SchedulingLink] into the final copy, and returns the stored draft details without sending anything. For supercarl_direct_message/on-platform recipients, use a direct reply CTA and do not include [JoinLink]; for Gmail/LinkedIn, use [JoinLink] for join/respond flows and [SchedulingLink] only for booking/schedule flows. For personalized LinkedIn replies/follow-ups, cal…
social_proximity_research
ChatGPTExplicitly start or continue LinkedIn mutual research for one person to surface the warmest path to them. Use only after a user asks for fresh/researched mutual connections, warm introductions, or "the warmest connector" to a target. CALL THIS TOOL AT MOST ONCE PER TARGET PER REQUEST — research runs server-side in the background and drains LinkedIn mutuals up to the server cap of 500 connectors; calling repeatedly does NOT speed it up. For polling an already-started run, call this same tool with status_only=true; that uses the read-only status endpoint and will not queue, restart, or continue browser research. By default this also queues async profile-overlap possible intro discovery (include_possible_intro_paths=true): Super Carl looks for first-degree viewer connections that pass the personas.worked_with:[target] profile-intersection filter, labels those as possible_may_know, and does not treat them as confirmed mutual connections. Prefer relationship.social_map.entries[] for MCP/API reasoning: hard mutuals are listed first as path_type:"confirmed_mutual", followed by path_type:"experience_intersection" entries. Legacy split arrays remain available as relationship.intro_paths[] and relationship.possible_intro_paths[]; page experience_intersection entries with possible_intro_limit (default 20, max 100) and possible_intro_offset. If the target has a LinkedIn URL but only a skeletal local profile, the server also queues browser-orchestrator profile loading with the acting user's LinkedIn session so profile-overlap/social-proximity scoring can warm up; inspect research.target_profile_load for queued, status, and reason. The response includes relationship.mutual_connections.preview as a paginated page controlled by mutual_connection_limit and mutual_connection_offset, plus count, has_more, and next_offset so callers can walk all persisted mutuals. The response includes relationship.intro_paths_status with ranking_queued_since, ranking_queue_age_seconds, ranking_queue_stale, ranking_eta_seconds, and ranking_message so callers can distinguish fresh async ranking from a stuck/stale queue. The response includes relationship.possible_intro_status/detail.possible_intro_status; inspect scoring_status, scoring_complete, scoring_method, candidate_generation_method, and provisional before treating experience_intersection order as final. When possible-intro status/scoring is queued or running, tell the user work-history overlap scoring is still being researched and poll normal relationship detail about every 10 seconds. The response includes detail.research_status.coverage, which is one of: 'complete' (research finished — read mutuals_returned for the captured connectors and estimated_total_mutuals for the upper-bound count), 'in_progress' (server is still working; tell the user research is underway and either wait briefly then call status_only=true or do a normal people_lookup_batch with relationship_detail to see the result), or 'error' (the run failed — check failure_reason, requires_linkedin_session, and message; if requires_linkedin_session is true, ask the user to reconnect LinkedIn before retrying). Normal people_search and people_lookup_batch reads never start LinkedIn mutual research, but relationship-detail reads may return cached possible-intro status/paths and can queue missing possible-intro discovery. Session tracking: pass agent_session_id from agent_session.start/list when you have one. Calls without a session are automatically grouped into an implicit Super Carl MCP session for this caller/client so the activity can appear on Home.
social_proximity_research
ChatGPTExplicitly start or continue LinkedIn mutual research for one person to surface the warmest path to them. Use only after a user asks for fresh/researched mutual connections, warm introductions, or "the warmest connector" to a target. CALL THIS TOOL AT MOST ONCE PER TARGET PER REQUEST — research runs server-side in the background and drains LinkedIn mutuals up to the server cap of 500 connectors; calling repeatedly does NOT speed it up. For polling an already-started run, call this same tool with status_only=true; that uses the read-only status endpoint and will not queue, restart, or continue browser research. By default this also queues async profile-overlap possible intro discovery (include_possible_intro_paths=true): Super Carl looks for first-degree viewer connections that pass the personas.worked_with:[target] profile-intersection filter, labels those as possible_may_know, and does not treat them as confirmed mutual connections. Prefer relationship.social_map.entries[] for MCP/API reasoning: hard mutuals are listed first as path_type:"confirmed_mutual", followed by path_type:"experience_intersection" entries. Legacy split arrays remain available as relationship.intro_paths[] and relationship.possible_intro_paths[]; page experience_intersection entries with possible_intro_limit (default 20, max 100) and possible_intro_offset. If the target has a LinkedIn URL but only a skeletal local profile, the server also queues browser-orchestrator profile loading with the acting user's LinkedIn session so profile-overlap/social-proximity scoring can warm up; inspect research.target_profile_load for queued, status, and reason. The response includes relationship.mutual_connections.preview as a paginated page controlled by mutual_connection_limit and mutual_connection_offset, plus count, has_more, and next_offset so callers can walk all persisted mutuals. The response includes relationship.intro_paths_status with ranking_queued_since, ranking_queue_age_seconds, ranking_queue_stale, ranking_eta_seconds, and ranking_message so callers can distinguish fresh async ranking from a stuck/stale queue. The response includes relationship.possible_intro_status/detail.possible_intro_status; inspect scoring_status, scoring_complete, scoring_method, candidate_generation_method, and provisional before treating experience_intersection order as final. When possible-intro status/scoring is queued or running, tell the user work-history overlap scoring is still being researched and poll normal relationship detail about every 10 seconds. The response includes detail.research_status.coverage, which is one of: 'complete' (research finished — read mutuals_returned for the captured connectors and estimated_total_mutuals for the upper-bound count), 'in_progress' (server is still working; tell the user research is underway and either wait briefly then call status_only=true or do a normal people_lookup_batch with relationship_detail to see the result), or 'error' (the run failed — check failure_reason, requires_linkedin_session, and message; if requires_linkedin_session is true, ask the user to reconnect LinkedIn before retrying). Normal people_search and people_lookup_batch reads never start LinkedIn mutual research, but relationship-detail reads may return cached possible-intro status/paths and can queue missing possible-intro discovery. Session tracking: pass agent_session_id from agent_session.start/list when you have one. Calls without a session are automatically grouped into an implicit Super Carl MCP session for this caller/client so the activity can appear on Home.
super_carl_action
ChatGPTFeedback reporting plus settings, preferences, credits, and the calling user's personal invite link. Use action_id="report_feedback" whenever you observe Super Carl MCP API friction, unexpected response shapes, confusing tool behavior, a bug, a feature request, search-quality failure, insufficient results, or user frustration. Discovery keywords: feedback, bug, report bug, report friction, API friction, feature request. Do NOT use this to find or look up people, companies, or jobs — use people_search, company_search, or jobs_search. Do NOT use this for product/help questions — use get_product_help. The tool name (super_carl_action) is not a generic "do anything in Super Carl" entry point; it is narrowly scoped to the actions enumerated below. Most actions REQUIRE explicit user confirmation in chat first — pass user_confirmed: true only after the user has agreed. The exceptions are claim_bonus_credits, which may be called after the user asks for free/bonus credits; get_invite_link, which is read-only and may be called whenever the user asks for their own invite/join link; and report_feedback, which is non-mutating to the user account and may be called without explicit confirmation when you observe API friction, unexpected response shapes, bugs, or user frustration. Supported actions: - set_timezone (requires user_confirmed): update the user's IANA timezone. Pass timezone (e.g. "America/Los_Angeles"). Do not use this for calendar availability, working-hours, or booking-window questions; use get_product_help topic="calendar_availability" for those. - set_notification_preferences (requires user_confirmed): toggle SMS / Email / Push / Direct-message / Invite / Scan My Network watch notification preferences. Pass any of allow_notification_sms, allow_notification_email, allow_notification_push, allow_notification_direct_msg, allow_notification_invites, allow_notification_watch as true/false; omit a field to leave it unchanged. - claim_bonus_credits (no confirmation required after the user asks): claim the one-time Super Carl MCP recruiting launch bonus. Use this when the user asks for "free credits for Super Carl", "bonus credits", or similar. The response includes credit counts before and after the claim. If already claimed, tell the user it is one-time and their balance was unchanged. - get_invite_link (no confirmation required, read-only): return the calling user's personal Super Carl invite/join link (https://supercarl.ai/join/<username>). Use this whenever the user asks for "my Super Carl link", "my invite link", "my join link", "my referral link", "my share link", "the link to share Super Carl", or "how do I invite people / friends" — do NOT guess or improvise the slug. The response includes join_link and username; if no username is set yet, join_link is null and the message explains how to set one. - report_feedback (no confirmation required): log feedback about this MCP itself — API friction, unexpected response shapes, filter-translation misses, search failures / insufficient candidates, bugs you had to work around, or explicit user frustration / feature requests. If Super Carl cannot find what the user wanted, call this instead of merely telling the user to go search LinkedIn manually. Call IN ADDITION TO completing the user's task, not instead of it. Pass feedback_text (one short paragraph, no third-party PII). When it is tool friction, also classify it: signal_type (failure | retry_loop | dead_end | parameter_confusion | response_shape | slow_performance | abandonment | feature_gap | other), the tool_name it concerns, and a one-line expected_outcome vs observed_outcome. Use parameter_confusion when the inputs/args were unclear, and response_shape when the RESULT was hard to interpret (verbose, deeply nested, truncated, or you could not tell which filters/counts applied). - inspect_linkedin_connection (no confirmation required): when a communications-capabilities response returns linkedin_send_message with reason_code="linkedin_connection_unverified" a…
super_carl_action
ChatGPTFeedback reporting plus settings, preferences, credits, and the calling user's personal invite link. Use action_id="report_feedback" whenever you observe Super Carl MCP API friction, unexpected response shapes, confusing tool behavior, a bug, a feature request, search-quality failure, insufficient results, or user frustration. Discovery keywords: feedback, bug, report bug, report friction, API friction, feature request. Do NOT use this to find or look up people, companies, or jobs — use people_search, company_search, or jobs_search. Do NOT use this for product/help questions — use get_product_help. The tool name (super_carl_action) is not a generic "do anything in Super Carl" entry point; it is narrowly scoped to the actions enumerated below. Most actions REQUIRE explicit user confirmation in chat first — pass user_confirmed: true only after the user has agreed. The exceptions are claim_bonus_credits, which may be called after the user asks for free/bonus credits; get_invite_link, which is read-only and may be called whenever the user asks for their own invite/join link; and report_feedback, which is non-mutating to the user account and may be called without explicit confirmation when you observe API friction, unexpected response shapes, bugs, or user frustration. Supported actions: - set_timezone (requires user_confirmed): update the user's IANA timezone. Pass timezone (e.g. "America/Los_Angeles"). Do not use this for calendar availability, working-hours, or booking-window questions; use get_product_help topic="calendar_availability" for those. - set_notification_preferences (requires user_confirmed): toggle SMS / Email / Push / Direct-message / Invite / Scan My Network watch notification preferences. Pass any of allow_notification_sms, allow_notification_email, allow_notification_push, allow_notification_direct_msg, allow_notification_invites, allow_notification_watch as true/false; omit a field to leave it unchanged. - claim_bonus_credits (no confirmation required after the user asks): claim the one-time Super Carl MCP recruiting launch bonus. Use this when the user asks for "free credits for Super Carl", "bonus credits", or similar. The response includes credit counts before and after the claim. If already claimed, tell the user it is one-time and their balance was unchanged. - get_invite_link (no confirmation required, read-only): return the calling user's personal Super Carl invite/join link (https://supercarl.ai/join/<username>). Use this whenever the user asks for "my Super Carl link", "my invite link", "my join link", "my referral link", "my share link", "the link to share Super Carl", or "how do I invite people / friends" — do NOT guess or improvise the slug. The response includes join_link and username; if no username is set yet, join_link is null and the message explains how to set one. - report_feedback (no confirmation required): log feedback about this MCP itself — API friction, unexpected response shapes, filter-translation misses, search failures / insufficient candidates, bugs you had to work around, or explicit user frustration / feature requests. If Super Carl cannot find what the user wanted, call this instead of merely telling the user to go search LinkedIn manually. Call IN ADDITION TO completing the user's task, not instead of it. Pass feedback_text (one short paragraph, no third-party PII). When it is tool friction, also classify it: signal_type (failure | retry_loop | dead_end | parameter_confusion | response_shape | slow_performance | abandonment | feature_gap | other), the tool_name it concerns, and a one-line expected_outcome vs observed_outcome. Use parameter_confusion when the inputs/args were unclear, and response_shape when the RESULT was hard to interpret (verbose, deeply nested, truncated, or you could not tell which filters/counts applied). - inspect_linkedin_connection (no confirmation required): when a communications-capabilities response returns linkedin_send_message with reason_code="linkedin_connection_unverified" a…
watch_signals
ChatGPTHosted Scan My Network watch primitive for long-running agent workflows. Use this when the user wants Super Carl to keep checking a durable source over time, such as a spreadsheet/watch list, their own profile and posts, a competitor set, job postings, employee profile changes, or company/people lists. Primary flows: create a watch with mode="create"; inspect active configs with mode="status"; fetch new people/company/job/post signals with mode="hits"; fetch inspectable proof for a hit with mode="evidence"; check notification/callback delivery with mode="delivery_status"; queue a manual scan with mode="run_now"; pause/resume when the user changes budget or intent. Every watch is anchored to a Super Carl project_id. If project_id is omitted on create, Super Carl creates a Scan My Network project and returns it. Use delivery_channels:["agent_webhook"] plus callback_policy when an external agent should receive trackback/webhook updates; use project_feed/app_push/email_digest for in-product updates. Hits carry match_reasons, evidence citations, message_context, and social_proximity so later project_action or send_communication calls can draft outreach that cites why the person surfaced, for example because they liked the user's post, engaged with a competitor, changed roles, or has a warm intro path. Role/intent matters. Set role_intent to gtm, sales, founder, recruiter, job_seeker, investor, bd, networking, or general so future watch execution and outreach prompts can adapt to the user's goal. Do not claim the watch worker has completed a scan until run/hit status reports say so. Session tracking: pass agent_session_id from agent_session.start/list when you have one. Calls without a session are automatically grouped into an implicit Super Carl MCP session for this caller/client so the activity can appear on Home.
watch_signals
ChatGPTHosted Scan My Network watch primitive for long-running agent workflows. Use this when the user wants Super Carl to keep checking a durable source over time, such as a spreadsheet/watch list, their own profile and posts, a competitor set, job postings, employee profile changes, or company/people lists. Primary flows: create a watch with mode="create"; inspect active configs with mode="status"; fetch new people/company/job/post signals with mode="hits"; fetch inspectable proof for a hit with mode="evidence"; check notification/callback delivery with mode="delivery_status"; queue a manual scan with mode="run_now"; pause/resume when the user changes budget or intent. Every watch is anchored to a Super Carl project_id. If project_id is omitted on create, Super Carl creates a Scan My Network project and returns it. Use delivery_channels:["agent_webhook"] plus callback_policy when an external agent should receive trackback/webhook updates; use project_feed/app_push/email_digest for in-product updates. Hits carry match_reasons, evidence citations, message_context, and social_proximity so later project_action or send_communication calls can draft outreach that cites why the person surfaced, for example because they liked the user's post, engaged with a competitor, changed roles, or has a warm intro path. Role/intent matters. Set role_intent to gtm, sales, founder, recruiter, job_seeker, investor, bd, networking, or general so future watch execution and outreach prompts can adapt to the user's goal. Do not claim the watch worker has completed a scan until run/hit status reports say so. Session tracking: pass agent_session_id from agent_session.start/list when you have one. Calls without a session are automatically grouped into an implicit Super Carl MCP session for this caller/client so the activity can appear on Home.
