Configuring Tools

What “Configuring Tools” Means

A REDA AI agent is the sum of its tools. Configuring an agent’s toolset involves three decisions:

• Which built-in tools the agent gets. The 18 platform-shipped tools are listed in the Built-in Tools Reference; assign only the ones each agent actually needs.
• Which custom tools you build for it. When the built-ins don’t cover a use case, build a custom tool of one of three types: SOQL Template, Apex Class or File Mapping.
• How tools are scoped. Each tool can be restricted to specific channels, agents and context objects so the right tool surfaces in the right context.

Assigning Tools to an Agent

Tools become available to an agent when they are explicitly assigned. The platform never auto-assigns tools to a new agent.

For governance, the assignment is per-agent. Two agents on the same channel can have completely different toolsets; the agent definition is the boundary.

Building Custom Tools — the Tool Builder

For anything the built-ins don’t cover, the Tool Builder walks you through creating a custom tool from a single screen. The builder is type-first — you pick what kind of tool you want, and the form adapts to that choice.

Step 1 — Pick a tool type

Three type cards sit at the top of the builder:

The card you pick is authoritative. The remaining sections of the builder collapse and rearrange around the type so you only see fields that are relevant.

Step 2 — Category locking

Each tool type has a sensible default category, and the builder enforces it visibly:

When a category is locked, the builder shows a lock notice explaining why — so admins don’t spend time trying to override a constraint that the runtime would reject anyway.

Step 3 — Configure type-specific fields

Each type opens a different set of configuration blocks. The detail lives on the dedicated pages:

• SOQL Template Tools — query template, placeholder syntax, auto-generated input schema.
• Apex Class Tools — executor class name, input schema, return contract, file-processing flag.
• File Mapping Tools — target object, operation, column-to-field mapping, match key.

Step 4 — Use the AI Generator

For each type the builder offers an AI Generator that produces a working tool from a short description and any reference inputs you provide:

• For SOQL Template tools, paste the query you want (or describe what you need) — the generator extracts placeholders and writes the input schema with rich descriptions.
• For Apex Class tools, describe the operation, optionally upload a sample file when the tool will process documents, and the generator produces the input schema and a sample of the data your executor will receive.
• For File Mapping tools, upload a sample CSV plus a one-line description; the generator proposes the target object, operation, mapping and match key.

The output is always reviewable — the generator fills the form, you edit anything that doesn’t fit, and you save when you’re happy.

Step 5 — Watch the live impact panel

Throughout the builder, an impact panel renders what the agent will actually see at runtime:

• The tool name and description as they will appear to the model
• The input schema in the exact JSON shape sent on every request
• The category, tier and channel scoping that govern when the tool is loaded
• For Action tools, a preview of the confirmation card the user will see
• For Apex Class tools with file processing, a sample of the extracted-data shape your executor will receive

This is the fastest way to spot mismatches between what you want and what the agent will see — before the first real conversation.

Step 6 — Save and assign

Saving deploys the tool through the Metadata API. The Tool Builder tracks the deploy and tells you when the tool is live. Once deployed, assign it to one or more agents through the agent’s Tools panel. Tools are not implicitly visible to agents — assignment is always explicit.

Scoping a Tool

Every tool definition has scoping fields that control where and when the tool surfaces:

Keeping the Toolset Lean

Each tool the agent has costs tokens on every request — the model sees the tool’s name, description and input schema even when it doesn’t use the tool. Optimisation comes from three habits:

Assign by need. Don’t over-assign in case the agent might need a tool one day. Add tools when a real conversation needs them; remove tools that haven’t fired in weeks.

Tighten verbose schemas. A tool’s definition is sent on every turn, so a bloated input schema is a per-turn tax. Keep descriptions crisp and fields minimal, and confirm with the Conversation Debugger what the model actually saw. See Tool Loading & Cost.

Replace describe-style tools with prompts when patterns are stable. If the agent always asks the same picklist questions about the same field, encoding that knowledge in the agent’s prompt is cheaper than calling get_picklist_values on every conversation. See Custom Prompts per Agent.

Set a hard ceiling per agent. The three habits above are judgement calls; two per-agent settings turn them into limits the agent cannot exceed. Max Tools caps how many tools this agent offers the AI per turn (1–100; blank behaves as 25) — a direct cap on the per-turn cost of the tool list itself. Max Tool Iterations caps how many steps the agent may take within a single turn when chaining tools together (3–25; blank behaves as 6), which is what stops an agent looping on a task it cannot finish. Both live in the Performance & Cost Controls section of the Agent Definition record; see Performance & Cost Settings.

Permission Errors at Runtime

Tools execute under the running user’s permissions. When a tool call fails because the user lacks access:

• The tool returns a structured error, not a stack trace
• The agent reads the error and explains it conversationally to the user
• The conversation continues — permission errors don’t crash the agent

This is the desired posture: the platform inherits Salesforce’s permission model, surfaces failures cleanly, and lets the agent help the user resolve them. There is no path that elevates the agent above the user’s normal access.

Best Practices

Build by intent, not by API surface. A tool called “Send Renewal Quote” that wraps a focused Apex method is far more reliable than a generic “Update Records” tool the agent has to figure out. Constrained tools produce predictable conversations.

Invest in tool descriptions. The agent’s decision to call a tool depends almost entirely on the description. Spell out what the tool does, when to use it, and what it doesn’t do.

Lock down what shouldn’t change. Use SOQL Template and File Mapping tools when you want a stable contract. Use Apex Class tools when you need flexibility. Don’t hand the agent more freedom than the use case actually needs.

Use the impact panel. The single fastest debugging step is to read the agent-eye view in the impact panel and confirm it matches your expectations.

Iterate with the Conversation Debugger. Once the tool is live, the Debugger shows every tool call the agent made, its inputs and its result. Most tool issues become obvious there.

Frequently Asked Questions

Next Steps

Read Action Confirmation for how Action tools surface to users, or pick a tool type to dive into: SOQL Template, Apex Class, or File Mapping.