Built-in Tools Reference

How to Read This Reference

Every built-in tool has the same anatomy:

• Category — Tool for read-only retrieval, Action for anything that writes to Salesforce.
• Confirmation — whether the agent shows an action confirmation card before running. All Action tools confirm by default; read tools never confirm.
• Channels — which deployment channels can use the tool. Some tools (deletes, internal notifications) are intentionally restricted to internal Salesforce users.
• Batch input — whether the tool accepts an array of inputs in a single call to reduce model round-trips.
• Tier — the tool tier the agent must have access to. See Tool Loading & Cost.

Built-in tools enforce field-level security, CRUD and sharing under the running user’s permissions — identical posture to a normal Salesforce session.

Read Tools

Read tools retrieve data and return JSON to the agent. They never write, so they don’t require confirmation.

soql_query

Runs a read-only SELECT query in user mode. CRUD, FLS and sharing are enforced. The platform appends a row LIMIT if the query has none, and length-caps the serialised result. Non-grouped aggregate queries are exempt from the auto-LIMIT so totals come back accurately. Use the batch form whenever the agent needs more than one query in a turn — it cuts model round-trips substantially.

describe_object

Returns the schema of one or more Salesforce objects: field API names, labels, data types, picklist references and relationship fields. Cached within the transaction so repeated calls in the same turn are free. Batch mode is the preferred form when the agent needs to learn about several related objects.

count_records

Returns the row count for an object, optionally filtered by a WHERE clause. Cheaper than soql_query when the agent only needs a number. Restricted to internal channels so guest-facing widgets can’t enumerate record volumes.

get_record

Returns a single record by ID. If fields isn’t specified, the platform returns up to fifty fields from the object the user can read. Use it when the agent already knows the ID and just needs the latest values.

get_picklist_values

Returns active picklist values for a field, with labels, API values and the default flag. Useful before the agent attempts to write a picklist field.

get_record_types

Returns active record types for an object. Use it before create_record when the destination object has multiple record types and the agent needs to choose the right one.

Action Tools

Action tools change Salesforce state. Every Action tool surfaces a confirmation card by default; the user must approve before the platform executes. Confirmation can be turned off per agent on internal channels using Auto Execute Actions; on external and community channels it stays on. See Action Confirmation for the full flow.

create_record

Creates a new record on the given object with the supplied field values. Validation rules, required fields and FLS apply — the agent will get a structured error response if the write fails.

update_record

Updates an existing record by ID with the supplied field changes. Only the fields the user can edit will actually change.

delete_record

Deletes a record by ID. Restricted to internal channels because it is destructive and irreversible. Confirmation cannot be auto-executed even on internal channels — the user must approve every delete.

create_task

Creates a Salesforce Task. Defaults to assigning the task to the running user; pass assigned_to to assign it to someone else.

create_event

Creates a Salesforce Calendar Event with start and end timestamps. The event is owned by the running user.

send_email

Sends an email through Salesforce as the running user. The agent should resolve the recipient’s email from a Contact or Lead record before calling. related_to_id attaches the email to a record for activity history; group_key groups several outbound emails into a single audit trail entry.

Choosing who the email comes from. Three optional inputs control the sender identity, and all three are driven by the agent’s instructions rather than by a setting. from_address names an organisation-wide email address to send as — it must already exist and be verified in Setup, and if it cannot be matched the email is still sent from the default sender and the mismatch is recorded, so an agent never goes quiet because of a typo. sender_display_name sets the friendly name the recipient sees, and applies only when no organisation-wide address is in play. reply_to decides where replies land — point it at an address wired to inbound routing and the reply comes back into the conversation. An agent whose instructions pass none of these behaves exactly as before. See Outbound Email.

Stamping your own fields on the email. Every email the agent sends creates an EmailMessage record in Salesforce. If you have added your own custom fields to that object — a category, a campaign code, a service-level flag — the optional field_values input lets the agent fill them in as it sends, so the email arrives already classified instead of needing a follow-up update. Pass it as a map of field API name to value, for example {"Outreach_Category__c": "Renewal", "Campaign_Code__c": "Q3-RENEW"}. Three rules govern it, and each one exists to stop a model-generated value doing damage:

• Custom fields only. Field names must end in __c. Standard fields such as Subject, Status or FromAddress are refused — those are set by the send itself, and letting the agent overwrite them would corrupt the record of what was actually sent.
• The field must exist and be writable by the running user. Names are checked against your org’s real schema before anything is written. Anything unrecognised is skipped, not guessed at.
• The email is never lost to a bad field. If a value cannot be applied, the send still succeeds and the agent is told exactly which fields were set and which were skipped — so it can report accurately rather than claim a stamp it did not make.

Nothing here is automatic: the agent supplies field_values only when its instructions tell it to, so existing agents are unaffected. If you want every email from an agent tagged the same way, say so in that agent’s Custom Instructions prompt and name the field and the value you expect.

send_custom_notification

Posts an in-app bell notification to a Salesforce user (this is the bell icon notification, not an email). Useful for nudging a colleague about a record the agent just created or updated.

link_file_to_record

Attaches an uploaded file to a Salesforce record by creating a ContentDocumentLink. If content_document_id is omitted, the most recently uploaded file in the conversation is used. This is the standard pairing for any agent that processes documents and then needs to attach them to the related record.

schedule_action

Defers another action to run later. Schedule by absolute timestamp, by relative offset, or by reply trigger (e.g. “send when the contact replies to this email”). The deferred work is created as a Scheduled Action record and executed by a scheduled job. See Scheduled Actions for the full execution model.

Conditions. An optional condition_field, condition_operator and condition_value are re-checked at the moment the action fires, so it only runs if the world still looks the way it did when it was scheduled. condition_operator must be one of equals, not_equals, contains, not_contains, is_blank or not_blank — typed exactly like that, in every language — and anything else is rejected when the action is scheduled. A condition that cannot be checked skips the action rather than letting it run.

get_context_prompts

Fetches any extra instructions configured for a specific record’s object and record type — useful when the user names a record that was not already part of the conversation’s context. It returns an empty list when there are none, which is normal, and the agent is instructed not to call it repeatedly for the same record.

continue_workflow

Requests one additional autonomous turn so a workflow can continue in a fresh transaction. It exists for the write-then-call-then-write case: the agent has just created or updated a record and now needs a callout (or another tool) that depends on the committed result. The next turn runs after the current changes commit, so the new records and their Ids are available to it. It is not a general-purpose “keep going” button — an agent can already read, reason and write several records within a single turn.

call_agent

Asks a different agent a question mid-conversation and returns its answer, so a general assistant can consult the agent that owns a specialist subject instead of guessing. The consulted agent answers with its own instructions, tools and data access, runs as the person using the assistant — so it sees no more than they could already see — and cannot carry out changes on its own: anything it proposes returns to the original conversation for confirmation. Each consultation costs an extra turn and is kept as its own conversation.

It only works once an administrator ticks both Agent Invocable and Allow Automated Requests on the agent being consulted, and how far consultations may chain is set by Max Agent Call Depth on the agent that asks. Availability alone changes nothing — the calling agent’s instructions decide when to consult. See Agent-to-Agent Delegation.

Channel Availability At a Glance

Batch Input Mode

Three of the read tools accept an array of inputs in a single call:

• soql_query — queries array (max 5)
• describe_object — object_names array (max 5)
• count_records — counts array (max 5)

Batch mode reduces model round-trips when the agent legitimately needs more than one piece of information of the same kind in a turn — e.g. describing three related objects before composing a query, or counting records across two filters at once. The single-input form continues to work; batch is opt-in.

Best Practices

Assign only what the agent needs. A focused tool list produces faster, more predictable conversations. There is no benefit to assigning every built-in tool to every agent.

Mind the channel. A tool restricted to internal channels won’t appear to a guest user on the External Widget — even if it is assigned to the agent. Check the channel column when an agent “forgets” a capability.

Lean on the read tools before writes. Pair describe_object and get_picklist_values with create_record so the agent picks valid field names and picklist values; this dramatically reduces validation-rule failures.

Pick the right tool for the question. count_records is much cheaper than soql_query when all the agent needs is a number; get_record is much cheaper than a full query when the ID is already known.

Clearer email, record and scheduled actions

Email actions distinguish a Contact or Lead recipient from the related business record, support To/Cc lists, and check the supported recipient opt-out cases. Contact/Lead values supplied as related records are handled as recipients instead of invalid activity links. Record confirmations surface fields that were not applied, rather than silently implying success. Plan steps are reconciled one-to-one; relative scheduled times retain UTC correctly. Disabled agents and disallowed nested actions are checked before confirmed execution. File-link confirmation reuses the supported access-aware path. New Pending or rescheduled time-based actions require a runnable scheduled processor; email-reply tracking and ordinary history/status updates remain valid. Delayed jobs run as their scheduler owner, not by impersonating the requestor. Host guidance reduces duplicate use of another email/calendar connector; it cannot guarantee the host's behaviour.

Frequently Asked Questions

Next Steps

Read Tool Loading & Cost for how tool loading and cost work, or Action Confirmation for the full confirmation flow that wraps every action tool.