SOQL Template Tools

What is a SOQL Template Tool?

SOQL Template is the lightest of the three Tool Builder types. Use it when:

• You want the agent to retrieve data with a query you control end-to-end
• You want to expose only specific parameters — not let the model author free-form SOQL
• The result is read-only — no inserts, updates, or deletes
• You don’t want to write Apex

The query itself is locked at design time. The agent can only choose which tool to call and what to pass for each declared parameter; it cannot rewrite the SOQL, change the object, or remove the WHERE clause.

How a SOQL Template Tool Works

Writing the Template

Placeholders use curly braces and follow standard identifier rules (letter or underscore first, then alphanumeric or underscore). For example:

SELECT Id, Name, AccountId, StageName, Amount, CloseDate
FROM Opportunity
WHERE StageName = '{stage}'
  AND CloseDate >= {start_date}
  AND CloseDate <= {end_date}
ORDER BY CloseDate ASC

At runtime the agent supplies stage, start_date, and end_date. Each value is escaped before substitution so a malicious or malformed input can’t break out of the query.

What you can use

• Any valid SELECT query, including parent-relationship and child-relationship subqueries
• Aggregate queries (COUNT(), SUM(), GROUP BY) — the platform skips its automatic LIMIT for non-grouped aggregates so totals come back correctly
• Multiple placeholders in a single query, in WHERE, ORDER BY, LIMIT, or anywhere a literal would normally appear
• Hard-coded conditions to scope what the agent can see — e.g. WHERE OwnerId = '{user_id}'

What is blocked

• Anything that isn’t a SELECT — INSERT, UPDATE, DELETE, UPSERT, MERGE and UNDELETE keywords are rejected at validation time
• Queries that resolve to no parameters but still need them — placeholders that aren’t in the input schema fail validation
• Templates above the field length limit on the SOQL Template field

Tool Definition Fields

Runtime Behaviour

Escaping & injection protection

Every parameter is passed through SOQL single-quote escaping before substitution, and the resulting query is checked again to confirm it’s still a single SELECT statement with no DML keywords. The agent cannot turn a SELECT into a DML operation, comment-out clauses, or stitch on a second statement.

FLS, CRUD & sharing

Queries execute in user mode. Objects, fields and rows the running user can’t see are not returned. This is the same security model the rest of the platform uses for built-in tools.

The one exception is an agent with Execution Context = System on the API channel, where object and field access is elevated. Record sharing is never elevated — the executor stays with sharing, so even an elevated agent gets more columns, never more rows.

Row caps

If the template has no LIMIT clause, the platform appends one based on the Max Query Rows Platform Setting. Aggregate queries that don’t group are exempt so totals are accurate. The serialised result is also length-capped by Max Query Result Length — oversized payloads are truncated and flagged so the agent doesn’t blow the model’s context.

Result shape

The agent receives a JSON object:

{
  "totalSize": 12,
  "showing": 12,
  "records": [
    { "Id": "006...", "Name": "Acme Renewal", "Amount": 25000 },
    ...
  ]
}

When the display is capped (more rows matched than the agent was shown), a note field tells the agent how many rows were returned versus how many it’s seeing.

One query per call

SOQL Template tools execute exactly one query per invocation. The platform’s built-in soql_query tool supports a batch mode that runs several queries in one round-trip; SOQL Template tools do not. If you need batch behaviour, either expose the built-in soql_query tool to the agent or move the logic into an Apex Class tool.

Security & Governance

• Parameters are escaped automatically. You don’t need to add quote handling to the template.
• SELECT-only enforcement. The query is rejected at validation and again at execution if it contains DML keywords.
• User-mode execution. CRUD, FLS and sharing rules are applied; the agent cannot see data the user couldn’t see in a normal Salesforce session.
• Locked at design time. The agent cannot edit the SOQL or the parameter schema. Changes require an admin to update the Tool Definition.
• Audit trail. The tool call and its result are recorded on the Conversation and Message records, including which tool was used and which parameters were passed.

When to Use SOQL Template vs the Alternatives

Best Practices

Constrain the query, not the agent. Bake hard limits into the template — specific record types, owner filters, status conditions — rather than relying on the agent to add them.

Name parameters semantically. {stage} and {close_date_after} are clearer to the model than {p1} and {p2}. The names appear in the schema the agent reads.

Always include the fields the agent needs to answer. The agent only sees what the SELECT returns. If the user’s likely follow-up is “who owns it?”, add Owner.Name to the SELECT now.

Add an explicit LIMIT for narrow results. Auto-LIMIT is a safety net, not a tuning tool. If you know the query should never return more than ten rows, say so in the template.

Test in the Tool Builder before exposing. The builder lets you run the template with sample parameter values and inspect the substituted query, the results, and any validation warnings.

Frequently Asked Questions

Next Steps

Read the Built-in Tools Reference for the platform-shipped tools you can expose to agents without any configuration, or move on to Understanding Context Fields to control what data is included automatically with each conversation.