Skill v1.0.0
currentTrusted Publisher100/100version: "1.0.0" name: salesforce description: Agentforce Sales connector guide for Sales workflows that use Salesforce for CRM reads, drafts, notes, account plans, Agentforce assignments, or proposed record changes.
Salesforce User Guide
Use this as the Salesforce-specific user guide whenever the user or workflow is using Salesforce as the CRM connector, including drafting Salesforce-backed updates, summaries, notes, account plans, Agentforce assignments, or proposed record changes. Keep the surrounding workflow skill authoritative for the sales task itself; this guide adds Agentforce Sales-specific metadata discovery, SOQL query selection, record reads, links, and write safety.
Do not use this guide when the workflow uses another CRM connector or no CRM connector.
Skill Configuration
User Context
Mandatory pre-answer gate: Invoke sales:user-context in preflight mode by loading [$sales:user-context](../user-context/SKILL.md) and running its preflight script before answering, searching connectors, retrieving evidence, or drafting output. Do not look for a callable MCP tool named sales:user-context. Use the returned sales_preflight envelope as authoritative for saved context, source-category mapping, final obligations, and conditional guidance. Do not read or reinterpret raw Sales state files unless preflight fails, local shell access is unavailable, or the user explicitly asks for raw state inspection.
Use returned user context as lookup hints and drafting guidance. Always verify Salesforce object and field metadata before querying or writing; saved user context does not replace describe_global, describe_sobject, record type checks, or write-safety confirmation.
Audience And Language
Write for Sales users, not plugin maintainers. This applies to final answers, setup/status readbacks, failure explanations, tool preambles, and mid-turn progress narration.
Translate implementation work into practical Sales impact: what Sales is checking, setting up, saving, or preparing, and why it matters. Avoid implementation terms such as preflight, state file, cache, raw connector id, heartbeat, targetThreadId, schema, API, runtime, metadata, and provider taxonomy unless the user asks for debugging details.
Source Links
When referencing sources inline, prefer clickable Markdown links over plain bracket labels whenever the source exposes a useful URL. Use the source title, record name, channel/thread, or meeting/date as the link text, for example a clickable Markdown link whose visible text is Meeting notes: May 19 or Slack thread: May 15-21. Use plain text labels only when no useful URL or stable connector-visible link is available, and say (no useful link available) when that absence matters.
Connector Boundary
The Salesforce CRM app in the Sales plugin is the third-party Agentforce Sales connector, bound in .app.json to app id REPLACE_WITH_SALESFORCE_APP_OR_CONNECTOR_ID.
Use only the Agentforce Sales surfaces that are actually exposed:
- Metadata and identity:
describe_global,describe_sobject,get_user_info. - Record lookup and reads:
get_record_id_by_name,get_record_details,get_activity_history. - Querying:
soql_queryonly. - Sales-specific reads:
query_calendar_events,get_account_plan,query_agent_type,summarize_conversation_transcript. - Writes and mutating sales workflows:
create_record,update_record,create_account_plan,assign_target_to_sdr.
Do not imply support for SOSL, global text search, query continuation, Bulk API, Composite API, Data 360, Tableau Analytics, Prompt Builder, Flow invocation, arbitrary invocable actions, generic Apex REST calls, delete, or upsert-by-external-id unless a future installed app explicitly exposes those tools. For cross-object keyword search, large exports, high-volume write jobs, delete/upsert needs, or analytics surfaces outside the exposed Agentforce Sales actions, state the missing connector surface and ask for a narrower Salesforce scope, exact object/field, exact identifier, or another approved tool.
Discovery And Identity
- Prefer discovery over guessing. Use
describe_globalfor object matching anddescribe_sobjectfor field matching before non-obvious queries or writes. - Use
get_user_infofor requests involving "my", "me", or the current Salesforce owner. - In
describe_sobject, check field API names, labels, data type, filterability, createability, updateability, nullability, picklist values, references, relationship names, and record type details when those properties affect the task. - Use record type fields when record type changes defaults, picklist choices, required fields, or layout-sensitive behavior.
- For relationship queries, do not guess relationship names. Use metadata for relationship field paths and child relationship names.
- Use user-facing labels in final answers when known, and API names only when needed for precision or follow-up.
Record Disambiguation
- Prefer exact name or id matches before broad text matching when locating records.
- Treat broad
LIKE '%...%'filters as candidate discovery, not proof of the canonical record. - Account names can match regions, subsidiaries, brands, domains, and email-like records. Do not silently pick the first result when multiple plausible records remain.
- Use available business context such as country, website, industry, owner, active opportunities, recent tasks, or the user's wording to disambiguate.
- If one additional targeted filter will not clearly disambiguate the result, present the candidate records to the user before taking write actions or using the record as the basis for a deal summary.
Reads And Queries
- Before authoring non-trivial SOQL, identify the target object, fields needed, filters, sort or limit requirements, whether the query is for display or analysis, and whether selectivity is a concern.
- Use
soql_queryfor structured reads, relationship fields, ordering, aggregation, semi-joins, anti-joins, and filters on fields Salesforce marks as filterable. - Generate the simplest correct query: select only fields needed for the sales task, include
Idwhenever records may be shown, linked, or used for follow-up, and add a reasonableLIMITunless the user asked for a complete scoped result. - Prefer filtering in SOQL rather than post-filtering. Use aggregates for counts and grouped summaries instead of loading unnecessary records.
- Confirm relationship names before querying. Use child-to-parent traversal for parent data from child rows, parent-to-child subqueries for child rows from parent records, and aggregate queries for rollups.
- Evaluate wildcard usage carefully. Broad
LIKE '%...%'filters are candidate discovery, can defeat indexes, and are not proof of the canonical record. - This connector does not support SOSL. If the user asks for keyword search, object-unclear search, cross-object search, or text search in fields that are readable but not SOQL-filterable, say that Agentforce Sales only exposes SOQL and ask for a narrower object, field, or exact identifier.
- This connector does not expose a separate query continuation tool. Use a SOQL
LIMITwhen total rows must be capped, tighten filters for high-volume requests, and state the connector limit when the user needs complete export-style coverage.
Reads And Display Context
- Prefer explicit field projections for business facts and exports.
- Use
get_record_id_by_namefor exact or near-exact name-to-id lookup when the next step needs a Salesforce id. - Use
get_record_detailswhen the task needs presentation-ready context such as layout fields, optional fields, display values, child relationships, or record-type-sensitive UI metadata. Pass bothCompactandFulllayout types unless the user asks for a narrower UI read. - Use
get_activity_historyfor Account, Contact, Lead, or Opportunity activity summaries. - Use
query_calendar_eventsfor Salesforce calendar or meeting questions. - Use
get_account_planfor account strategy, plan, relationship, challenge, or status context. - Use
summarize_conversation_transcriptonly after resolving a specific VoiceCall or VideoCall id. If the call is unknown, query VoiceCall and VideoCall separately withsoql_query, then ask the user which call to summarize. - If a requested field is absent from a UI/layout-oriented response, retry with explicit fields before concluding the field is unavailable.
Query Traps And Recovery
- Do not use
WHEREfilters on fields that Salesforce reports as not filterable. - Long text and rich text fields are common traps: they may be readable in
SELECTbut rejected inWHERE. - A key example is
Task.Description: do not useWHERE Description LIKE .... Because Agentforce Sales does not expose SOSL, ask for a narrower filterable field, exact record, date/owner/status filter, or another approved search surface. - If a field or object is unknown, call
describe_sobjector use a narrowFieldDefinitionSOQL query before retrying. - If the first result set is too broad, tighten by object, date, owner, status, or another confirmed filterable field rather than adding unsupported text filters.
- Prefer standard, commonly present fields on
Account,Opportunity,Contact,Task, andEventbefore optional org-specific fields or relationship-heavy objects. - Do not assume optional fields or objects exist, including
CurrencyIsoCode,AnnualRevenue,OpportunityTeamMember,AccountTeamMember,Opportunity.Contact,OpportunityContactRole.Name,PricebookEntrySOSL, orFieldDefinition.IsCustom. Describe the object/field first, or omit the optional enrichment when the standard record data is enough. - Cap recovery from invalid schema/query errors. After two focused schema or query-shape failures for the same fact, fall back to safer standard fields, SOSL, exact record reads, or a clear evidence gap instead of continuing exploratory retries.
- Distinguish connector auth/runtime failures from schema misses. A message that explicitly says reauthentication is required should produce a re-auth CTA; MCP startup, handshake timeout, transport, or availability errors should be described as connector readiness/runtime issues and should not be framed as proof that the user must reconnect.
Writes
Write only when the user explicitly asks to create or update Salesforce data, create an account plan, or assign a Contact or Lead to Agentforce Lead Nurturing.
- Confirm object API name, record id, and field API names before writes.
- For
update_record, send only changed fields infields. For Agentforce AI-generated text updates on core sales objects, only use fields the tool permits, especiallyDescriptionwhen that is the documented allowed target. - For
create_record, send only intended create fields and include record type fields only when record type affects defaults, picklists, or createability. - Use
create_account_planfor account plan creation instead of generic record creation. Its body must includeAccountId,Name, the challenge, competitive, relationship, and strategy fields,StartDate, andStatus; resolve the account and gather, derive from grounded Salesforce/source evidence, or ask for any missing required values before calling the tool. - Before
assign_target_to_sdr, callquery_agent_typeto list available Agentforce Lead Nurturing or SDR agents, present the choices, and get the user's selection. The target must be a Contact or Lead id. - Stop if the user asks to delete, upsert by external id, call Apex REST, invoke Flow, or run arbitrary custom Salesforce automation; those operations are outside this Agentforce Sales connector surface.
- After any write, inspect the response and, when the response does not prove the outcome, verify with returned fields,
get_record_details, or a narrowsoql_querybefore summarizing the result.
Agentforce Sales Workflows
- Use
create_account_planandget_account_planfor account planning requests, but report Salesforce or connector errors plainly if the org does not support the AccountPlan object or the action returns unsupported-object errors. If the user only provides an account name or id, treat that as the target account, not as enough input to create the plan; first resolveAccountId, propose or collect the required plan body, and proceed only when the required fields are present. - Use
query_agent_typeandassign_target_to_sdrfor Agentforce Lead Nurturing assignment only when the user asks for that assignment. Treat assignment as a mutating workflow. - Use
query_calendar_eventsfor Salesforce Event records tied to calendar or meeting questions. - Use
summarize_conversation_transcriptfor voice or video call summary requests after resolving the call id with SOQL or user input.
Output
Return concise, business-facing results. Include clickable Salesforce record links only when a runtime source provides the org base URL, record URL, or instance URL.
Link rules:
- Prefer a record URL returned by the connector.
- If connector metadata exposes an org or instance base URL, construct links with that base:
https://<org-or-instance-base>/lightning/r/<ObjectApiName>/<Id>/view. - If only
Idis known and no trusted base URL is available, show the object label and id instead of inventing an org-specific URL.