Salesforce Agentforce: Writing Action Descriptions That Actually Work

💬 In plain words: The Agentforce AI model chooses which action to call by reading its description. It does not look at the action's name, and it does not read the underlying code. Therefore, an action description is not documentation for human developers—it is the strict selection criteria the model uses to choose between a dozen different tools.

📌 Example: Naming an action "Creates an appointment" is incredibly weak. A strong description looks like this: "Books a field crew visit for a specific meter on a chosen date. Returns the booking reference and confirmed date. Use only after checking whether the fault is on the customer's side."

🎬 Real-Life Example: The Action That Never Got Called

The Old/Bad Way: A development team built a flawless Apex action to check for system outages. They lazily set the description to: "Outage utility method."

Why it failed: The AI model relies purely on descriptions to make decisions. The description they provided explained the implementation to a developer, not the situation where the AI should use it. As a result, the model never selected the action. Instead, the agent fluently (and often incorrectly) hallucinated outage answers based on general Knowledge articles.

The New/Good Way: The team rewrote the description to: "Returns whether a supply address currently has a confirmed outage, its cause, and whether an estimated resolution is available. Use before telling a customer anything about restore times." They also gave the output variables clear, meaningful names.

The Payoff: The action fired perfectly. Not a single line of Apex code was changed—only the descriptive sentence telling the AI when to reach for that specific tool.

Core Concept: Writing for the Model

Vague descriptions cause wrong-action selection far more often than incorrect underlying logic does. If you hand your action list to a colleague with no context and they hesitate on which tool to use for a given prompt, the AI model will hesitate too.

• The 4-Part Structure: Write descriptions that explicitly state: what it does, what it needs, what it returns, and when NOT to use it.
• Variable Names Matter: Input and output variable names are also read by the AI model. Name them for semantic meaning (e.g., ConfirmedOutageStatus), not for developer convenience (e.g., outageBool).
• Consistent Discipline: The exact same discipline applies to subagent descriptions. The mechanism is identical, just one architectural level up.

A Perfect Action Description = 4 Elements:
├─ WHAT it does
├─ WHAT it needs (inputs)
├─ WHAT it returns
└─ WHEN NOT to use it

Bad: "Outage utility method"
Good: "Returns whether an address has a confirmed outage. Requires Zip Code. Returns Status string. Do not use for billing inquiries."

🧠 Criteria, not documentation: You are not describing the code to a fellow developer. You are telling an AI model exactly when it should reach for this specific tool.

🧭 360 Card — Descriptions as Selection Criteria

• Rule: Every action description must name what it does, what it needs, what it returns, and when to avoid it.
• Gain: Correct action selection. This is invisible when it works flawlessly, and absolutely baffling to debug when it fails.
• Price: Writing genuinely good descriptions is slow and can feel like documentation busywork.
• Limits: You are allowed 15 actions per subagent. The more actions you pack into a single list, the more critical your description quality becomes to prevent overlaps.
• Mirror (Short technical names): Great for developers saving keystrokes; completely useless to the AI engine actually choosing the tool.
• Future Proofing: Later in your development cycle, these descriptions will become part of your test assertions (where you assert which action fired based on the prompt).
• At Volume: Crowded action lists degrade tool selection the exact same way crowded subagent lists degrade routing.

⚠ INTERVIEW TRAP: Do not say the model picks an action "based on the conversation context." It picks based strictly on your action descriptions. Knowing that distinction is the difference between someone who just skimmed the marketing docs and someone who has actually debugged an agent trace.

Core Q&A & Interview Prep

Q: How exactly does the Agentforce agent know which action to call?

🎯 Say this first: "It reads the descriptions. That is exactly why I write my descriptions as strict selection criteria, not as developer documentation."

A: The description is the actual routing mechanism, and it is the single most underestimated part of building an AI agent.

• The model is forced to choose between up to 15 different tools, and the only context it has is the text description of each.
• Because of this, you must write four specific things into every description: what it does, what it needs, what it returns, and when not to use it.
• Input and output variable names matter heavily, because the model reads those to understand data mapping.
• Vague descriptions cause far more "wrong-action" problems than incorrect underlying code. Worse, the failure is quiet—the agent answers from a different source (like a Knowledge base) and sounds perfectly fine, even if it's hallucinating.
• Always verify from the system trace that the intended action actually fired, rather than just assuming it worked based on the chat interface's reply.