/platform-metadata-grounding-get

name: platform-metadata-grounding-get
description: "Find metadata that already exists in a Salesforce org by meaning, when you do not know its exact API name. Use to find objects, fields, flows, Apex classes, picklist values, permission sets, validation rules, record types, and sharing rules by what they store or do. Use before creating metadata to check whether something similar already exists, and before writing Apex, LWC, SOQL, or Flow logic to confirm the real names. Use to read how a field, object, or validation rule is configured, and which profiles and permission sets can read or edit a field. Works through the Metadata Grounding MCP (search_metadata, query_metadata, describe_metadata) or the Salesforce MCP operations searchMetadata, queryMetadata, and describeMetadata. Needs Salesforce Catalog in the org. DO NOT TRIGGER for choosing between grounding, SOQL, and the CLI (use platform-metadata-discovery-get), retrieving source (platform-metadata-retrieve), or Data Cloud DLO and DMO schema (data360-code-extension-generate)."
metadata:
  relatedSkills:
  - data360-code-extension-generate
  - platform-metadata-discovery-get
  - platform-metadata-retrieve
  version: "2.2"
  accessCheck: "CDP.orgHasUnifiedCatalogProvisioned"
  domains:
  - "Platform"
  mcpTools:
    metadata-grounding:
      tools:
      - "search_metadata"
      - "query_metadata"
      - "describe_metadata"
      semver: ">=1.0.0"
    headless-360:
      tools:
      - "describe"
      - "dispatch"
      - "dispatch_readonly"
      semver: ">=1.0.0"
  cliTools:
  - tool:
    - "sf"
    semver: ">=2.0.0"
id: "platform-metadata-grounding-get"

Salesforce Metadata Grounding

Metadata grounding searches the org's Salesforce Catalog, an index of the org's metadata with names, labels, descriptions, and configuration properties. It finds metadata by meaning, so "customer rewards status" can find a field labeled Loyalty Tier. It has three read-only operations: search, query, and describe.

Results are ranked and capped. They are never a complete list, and grounding never returns source.

When Not to Use Grounding

• Questions about standard Salesforce features or product behavior that do not depend on this org.
• A name you already know. Check it with scoped SOQL, which is exact and real time.
• A complete list, a count, or proof that something does not exist. Use scoped SOQL or `sf org list metadata`.
• Source to edit or deploy. Retrieve it with `platform-metadata-retrieve`.
• Where something is used, or what breaks if it changes. Grounding has no reference data.
• Metadata already returned in this conversation that has not changed since.

`platform-metadata-discovery-get` picks the right tool for each of these.

Pick the Server

Two servers reach the same catalog and return the same results. Use one server per request, never both for the same lookup.

The Salesforce MCP is shown in Setup today as the Headless360 (H360) MCP Server. On that server, `searchMetadata`, `queryMetadata`, and `describeMetadata` are operation ids that you pass to `describe` and `dispatch`. They are not tool names. The tools `search_metadata`, `query_metadata`, and `describe_metadata` exist only on the Metadata Grounding MCP.

| Order | Server | How to call | |---|---|---| | 1 | Metadata Grounding MCP | Call `search_metadata`, `query_metadata`, or `describe_metadata` with the inputs below. | | 2 | Salesforce MCP, when the Metadata Grounding MCP is not connected or keeps failing | Call `describe` on the operation id `searchMetadata`, `queryMetadata`, or `describeMetadata`. Do not use `discover`, and do not describe the grounding recipe, which is too large to read. Then call the path `describe` returns with the same inputs. Use `dispatch_readonly` for `searchMetadata` and pass the inputs as query parameters. Use `dispatch` for `queryMetadata` and `describeMetadata`, which are POST calls but only read, and pass the inputs as the JSON body. Do not use other metadata search operations. | | Neither connected | | Grounding is not available. Use the name and label fallback in `platform-metadata-discovery-get`. |

When a Call Fails

| What happens | What to do | |---|---| | The error says Salesforce Catalog is not enabled, or the user lacks the Customize Application permission | Stop using grounding on both servers for the rest of the session. Use the fallback and tell the user why, once. | | Any other error or a timeout | Retry once. If it fails again, use the next server for this request. After failures on two requests, use the next server for the rest of the session. | | The tool or server is not present | Start with the next server. |

A missing tool, an access error, or a 404 is not proof that the metadata does not exist.

Response Shapes

| Call | Metadata Grounding MCP | Salesforce MCP | |---|---|---| | Search | `{results, totalCount}` | Same payload in the response body | | Describe and query | Wrapped as `{defaultExc: "<json string>", responseCode}`. Parse the `defaultExc` string to read `types`, `typeDetails`, or `records`. | Payload in the response body, not wrapped | | Error | An array of `{errorCode, message}` | Same array in the response body |

Handle both shapes. If the response has a `defaultExc` string, parse it. Otherwise read the payload directly.

Catalog Type Names

Type names are case-sensitive, and some differ from Metadata API names.

| Metadata API name | Catalog type | |---|---| | CustomObject | `SObject` (subtypes `CustomObject`, `StandardData`) | | CustomField | `SObjectField` (subtypes `CustomField`, `StandardField`, `CustomPersonAccountField`) | | GlobalValueSet, StandardValueSet | `PicklistValueSet` (subtypes `Global`, `Standard`, `Local`) | | FlexiPage | `Flexipage` | | CustomTab | `Tab` | | CustomApplication | `TabSet` | | QuickAction | `QuickActionDefinition` | | Queue | `Group` with subtype `Queue` | | Role | `UserRole` |

Most other types use the Metadata API name, for example `ApexClass`, `ApexTri