TL;DR
- Agents can only reason over Salesforce as well as they can read the org — and metadata is the map.
- No single API gives the full picture. Reading the org well means combining at least five surfaces: REST Describe, Tooling API, Metadata API, UI API, and dependency/history data.
- Retrieval does not mean reasoning. The gap between an agent that talks about Salesforce and one that acts inside it safely is an actual context layer on top.
*****
AI agents can only reason over Salesforce as well as they can read the shape of the actual org.
That's the whole thesis, and it's the part that most "AI inside Salesforce" pitches walk right past.
There's a tendency to treat the model as the agent — as if reasoning emerges from the weights and everything else is just plumbing. Well, no. An agent's ability to act safely inside an enterprise org is bounded by its ability to read the org: every object, field, relationship, automation, permission, layout, Apex class, flow, dependency, and recent setup change. That's the map. Without it, the agent is improvising in production.
You could defer this problem for a long time.
Then Salesforce announced Headless 360, and the deferral ended. Salesforce now positions every platform capability as an API, an MCP tool, or a CLI command — meaning agents call into the platform directly, not through a browser session.
Their messaging has been pretty explicit: agents need access to data, workflows, business logic, permissions, sharing rules, and compliance controls
The question for any team building or buying agentic capability on Salesforce is no longer whether agents can act on the platform. They can. The question is whether they understand what they're acting on.
Metadata is the map, data is the territory
Salesforce metadata is the configuration and code that define how the org behaves. Custom objects, fields, page layouts, flows, validation rules, Apex, profiles, permission sets, record types, automations, feature settings — all of it. The Metadata API exists to deploy, retrieve, create, update, or delete that customization information. It's a different surface from the REST and SOAP APIs that move records around.
When an agent reads Salesforce, it's pulling from at least four distinct layers.
The schema layer — objects, fields, types, relationships, picklists — usually arrives through REST Describe, the Tooling API's EntityDefinition and FieldDefinition objects, and the UI API.
The configuration layer — layouts, record types, validation rules, flows, permission sets, profiles — lives behind the Metadata API and Salesforce DX source format.
The code and logic layer — Apex classes, triggers, LWC, Aura, formulas, flow XML — comes through Metadata API and Tooling API, often parsed alongside SymbolTable references.
The dependency and history layer — what's used where, what changed when, what depends on what — relies on MetadataComponentDependency, SymbolTable, SetupAuditTrail, and source tracking.
The important detail: no single endpoint gives an agent the complete, current, dependency-aware story of an enterprise org. Metadata is distributed by design. Reading it well means combining surfaces.
The five doors into the org
REST Describe is the fast schema scan.
Describe Global lists every object available to the calling user. sObject Describe gives field-level detail — types, nullability, calculated state, picklist values. It's where an agent starts when it needs to answer "what fields exist on Account" or "what type is Renewal_Date__c." It's also where naive agents stop, which is a problem we'll come back to.
Tooling API is the precision instrument.
It exposes queryable metadata objects — FieldDefinition, EntityParticle, ApexClass, ApexTrigger, MetadataComponentDependency — that let an agent inspect targeted pieces of the org without retrieving entire XML bundles. It's the right tool for interactive questions, dependency checks, and pre-change investigation. Tooling API also unlocks code-level analysis: SymbolTable contains the position, name, and references for Apex classes and triggers, with the caveat that ApexClass SymbolTable doesn't include references — you need ApexClassMember for that.
Metadata API is the heavy retrieval layer.
It pulls full components — custom objects, flows, validation rules, permission sets, layouts, Lightning pages, Apex, custom metadata, settings — as XML bundled into a .zip with a package.xml manifest. This is the right surface when an agent needs the complete configuration of something, not just its definition. And it's where metadata coverage matters: support varies by metadata type, API version, and channel. Salesforce maintains the Metadata Coverage Report precisely because the answer to "can this be retrieved or deployed programmatically" is not uniform.
UI API is the user-aware metadata layer.
It returns object metadata, layout information, picklist values, and theme information — all in a form that respects field-level security and user context. This matters more than it sounds. A field can exist on the object, appear on the layout, and still be invisible to a given profile. An agent that doesn't read for user context produces recommendations that are technically correct and operationally useless.
MetadataComponentDependency is the relationship layer, and it's where the gap between "reading Salesforce" and "understanding Salesforce" gets most visible.
The Tooling API exposes dependency relationships between metadata components, queryable through SOQL. But it caps at 2,000 records in a single query, doesn't include reports, and Salesforce points to Bulk API 2.0 for larger-scale dependency retrieval. Native dependency data gives the agent a partial graph — which is better than nothing, but also worse than enough.
Reading is not understanding
Ah yes, this trap.
A team builds an integration that pulls metadata through these surfaces. The agent can now list objects, fields, and flows. It feels like it understands the org.
It doesn't.
Retrieval is raw material. Reasoning needs structure. The difference between an agent that talks about Salesforce and an agent that works inside it is what happens between the retrieval and the response.
A few failure modes from the field:
Confusing data access with metadata understanding. A record query tells the agent what's in Salesforce. Metadata tells it how Salesforce works. Agents that conflate the two end up recommending changes based on data shape rather than configuration reality.
Inspecting fields without checking usage. A field can look unused from the object definition while appearing in a flow, a validation rule, an Apex trigger, a managed package reference, a report, a permission set, and a downstream integration. MetadataComponentDependency catches some of this. Static parsing of Apex and flow XML catches more. Nothing catches all of it on its own.
Reading XML without reading business logic. Flow XML describes what happens. It rarely explains why. The agent has to connect XML structure, naming conventions, descriptions, related objects, test coverage, and change history to recover intent.
Skipping permissions. A schema-correct change can still create a security incident. UI API and permission metadata exist for a reason.
Treating retrieval as reasoning. Pulling metadata only gives the agent raw material. Without a normalized inventory, a dependency graph, and a retrieval layer that surfaces the right slice at the right moment, the model is reasoning over noise.
The moment of truth: "Can we delete this field?"
The honest test of a metadata agent is what happens when you ask it something that looks small.
Can we remove Legacy_Status__c from Account?
A weak agent checks the field exists, maybe greps Apex for the name, and returns a confident answer.
A strong metadata agent assembles an evidence packet.
- Field definition: type, requiredness, formula or default behavior.
- Object relationships: lookups, formulas, rollups that reference it.
- Automation: flows, workflow rules, process builders, validation rules.
- Code: Apex classes and triggers, SymbolTable references where available.
- UI: layouts, record pages, compact layouts, related lists.
- Access: profiles, permission sets, field-level security. Reporting: dashboards and reports where indexed.
- History: SetupAuditTrail, recent source changes. Deployment: metadata coverage and validation constraints. Risk: what breaks, who notices, what migrates, what tests need to run.
And then it produces something like:
The field looks safe at the schema level, but it's still referenced by two flows, one validation rule, and three permission sets. Remove it only after updating Renewal Routing and Enterprise Account Validation, then run the Account trigger test suite and validate the deployment in a sandbox.
That's the difference between a generic chatbot and an actual agentic systems layer. Not the model, the context the model is reasoning over.
From metadata access to governed action
Salesforce is doing the work of making the platform more agent-readable. Headless 360, the DX MCP server, Metadata API Context MCP tools — all of it points the same direction: agents will increasingly call platform capabilities directly, and the surface area for autonomous work will expand.
That doesn't remove the complexity of an enterprise org. It changes who has to understand it.
When an agent can propose, generate, and deploy changes, the context layer between speed and risk becomes the actual product. Metadata access is the starting point. What sits on top of it — a unified view of every component, a dependency graph that survives across discovery, design, and build, impact analysis that runs before a change ships, governance that constrains what an agent can do without forcing a human to babysit every action — is where enterprise systems work happens now.
This is what Sweep builds
The agentic layer for enterprise systems is the difference between an agent that can read Salesforce and one that can act on it safely. We connect to the metadata surfaces Salesforce exposes. We contextualize that metadata into a Unified Metadata Graph that preserves relationships, dependencies, and history. We let agents act inside that context, with the impact analysis and governance the work actually requires.
If you’re curious how it works, and how it can benefit you, book a demo with us here.
