Original OrbTrail analysis expanded with complementary research, practical context and verified references.
A Salesforce Admins Podcast episode published on August 13 puts metadata readiness back at the center of Agentforce delivery. Guest Skye Tyler describes a familiar situation: people can interpret four similar date fields because they know the process and years of exceptions; an agent does not share that institutional memory. When names, descriptions and help text fail to distinguish them, the model must choose with insufficient context. Its answer may sound correct and may even work repeatedly, but repeated success does not turn a probabilistic choice into a dependable rule.
The lesson is not that every hallucination starts with an empty field description. Stale data, conflicting instructions, poor retrieval, permissions, weak action contracts and model limitations can also produce incorrect output. Metadata is one context layer. It is unusually important in Salesforce, however, because it describes both the business data model and the automations and agent components that act on it. Ignoring that layer leaves the planner inferring the meaning of custom elements that could not have existed in the model's general training.
The podcast recommends incremental work. Rather than promise a complete org cleanup, a team starts with the process the agent will support and reviews the objects, fields, automations and integrations within that process. OrbTrail adds a necessary finish line: the improvement is complete only when the same request suite, run before and after the change, shows more consistent subagent selection, action selection and outcomes. Without that comparison, adding descriptions improves documentation but does not demonstrate reliability.
Map the actual reach
List objects, fields, Flows, actions, subagents and external systems the use case can query or execute.
Remove competing meanings
Clarify purpose, usage rule, unit, source and exclusions wherever planners and people must interpret a component.
Preserve the request suite
Capture common questions, ambiguities, exceptions and expected results before changing metadata.
Test route and response
Measure subagent, action sequence and outcome; reject fluency gains that leave the underlying decision wrong.
Field descriptions help, but the planner sees a larger chain
Joshua Birk's metadata-as-blueprint article explains that Agentforce can use descriptions on objects, fields, formulas and actions to understand customizations. Current Agentforce documentation exposes the other half: the agent has metadata of its own. Bot and BotVersion identify the agent and version; GenAiPlannerBundle contains subagents and actions; GenAiPlugin represents a subagent; GenAiFunction represents an action; and plugin instructions guide behavior. The question ‘which description should we improve?’ cannot stop in Object Manager. A perfectly documented field can still be consumed by the wrong action when two subagents overlap or their contracts are vague.
Imagine a renewal agent with Renewal Date, End Date and Cancellation Deadline. A useful description does not repeat the label. It states the represented event, system of record, relevant time zone or granularity, and circumstances in which the field must not be used. The contract lookup action needs equally precise inputs and outputs, while the subagent must define which requests belong to its job. Review the full semantic chain: user request, subagent, action, object, field and answer. Contradictions usually become visible only when these layers are placed together.
Clean to the agent boundary and make everything else unreachable
Incremental cleanup controls cost only when agent scope is a technical boundary rather than an intention written in a slide deck. The podcast warns that an agent may explore related records when it finds a plausible connection. Inventory must therefore start from actions that are actually available, fields they return, permissions of the runtime identity and every external system that contributes context. Anything outside the use case should be removed from the surface or explicitly blocked, not merely left undocumented in the hope that the model ignores it.
That boundary also prevents destructive cleanup. Renaming API names, changing types or deleting fields can break Flows, Apex, rules, reports and integrations. Improving a description or help text often adds context without altering a technical contract; elsewhere, ambiguity exposes duplication that deserves controlled refactoring. Dependency analysis, process ownership, sandbox validation and rollback determine the choice. The aim is not to make every metadata component aesthetically pleasing to AI. It is to make the reachable set unambiguous while preserving compatibility for people and automation.
The evidence for cleanup is a measurable behavioral change
The Agentforce Testing API separates checks that can locate the improvement. A subagent test compares the chosen route with the expected subagent; an action test checks the action sequence; and an outcome test semantically compares expected and actual results. Coherence, completeness, conciseness, latency and instruction-adherence evaluations add further signals. For metadata work, route and action should lead the evidence. A better-written response that still queries the wrong field is a regression disguised by fluency.
Capture a baseline before editing. Include user synonyms, incomplete questions, similarly named fields, missing values, and cases where the agent should ask a clarifying question or refuse. Run the identical suite after the change and inspect failed conversations. Correct subagent and action selection can serve as the primary measure, with semantic outcome as a second layer. Operational measures such as escalation, rework and human correction become useful later, once volume and instrumentation support responsible attribution.
AI metadata belongs in the ordinary change process
The risk returns in the next sprint if descriptions are treated as a pre-launch cleanup campaign. The podcast recommends updating related metadata whenever an object or Flow changes and requiring review for every new agent process. Salesforce's recent Center of Excellence guidance extends that idea with named schema-change ownership, a technical-debt register, a data-quality baseline and an AI governance policy. Its recommended cadence is continuous and operational rather than a quarterly committee detached from delivery.
A practical change gate asks whether any field, action or output changed meaning; whether the access boundary expanded; whether descriptions and instructions remain consistent; and whether the representative suite passed. Store agent metadata, test definitions and approved results with the promoted version. The conclusion is less glamorous than changing models but more actionable: Agentforce does not absorb a company's private conventions by osmosis. If the system does not record what each component means and the delivery pipeline does not test how that meaning is used, the agent will keep filling gaps with probability.
