Developer guides

Agent tool REST API

Use this guide when an approved hosted service must call the versioned Record Health Check REST boundary.

Use this API only as the Salesforce boundary for an approved Agentforce or MCP service identity. Native in-org Agentforce actions remain the preferred user-context integration.

Use this page when implementing the Salesforce REST boundary. This is not an Agentforce Builder Setup guide. Card and Flow administrators should use the Lightning or Flow pages instead.

Choose this integration

The version 1 REST API exposes two read-only operations over one POST endpoint. It exists so a separately hosted MCP server can call the same Record Health Check engine used by Lightning, Flow, Apex, and native Agentforce actions.

Use the native Agentforce actions when evaluation must use the configured Agentforce principal. Use this REST API only when the dedicated integration principal’s access model is approved for the business purpose.

Endpoint

The unpackaged development route is:

/services/apexrest/record-health-check/contract-1/evaluations

Salesforce adds the package namespace segment for a namespaced installation. Confirm the installed route during package verification. For the rhc namespace, the expected route is:

/services/apexrest/rhc/record-health-check/contract-1/evaluations

The resource accepts POST with Content-Type: application/json. Other methods are not exposed.

Access

The Salesforce user associated with the OAuth token is the running integration principal. Assign that user the packaged Record Health Check MCP Integration (rhc__Record_Health_Check_MCP_Integration) Permission Set. It grants only Record Health Check Run, Apex class access to RecordHealthCheckAgentRestResource, and read access to both Record Health Check Custom Metadata Types. The REST adapter calls the framework internally; callers do not need direct Apex class access to RecordHealthCheck.

Separately grant read access, field access, sharing, restriction-rule access, and scoping-rule access required for the target records and configured Checks. Do not grant Record Health Check User, diagnostics, UI, Flow, Agentforce, async Apex, or lifecycle-event access merely to make the REST integration work.

Use a Salesforce External Client App or supported connected app with a dedicated integration user, client-credentials policy, narrow OAuth scopes, managed secret storage, rotation, and revocation.

In Setup, assign the packaged Record Health Check MCP Integration Permission Set. Create a separate organization-owned data-access Permission Set containing only the target objects and fields required by approved Checks, and assign both sets only to the dedicated integration user.

The endpoint is read-only with respect to business data. It always forces result-event publication to NONE, so an MCP or REST caller cannot produce Check Set Run or Check Result Platform Events.

Basic request pattern

Run one Check:

{
  "operation": "RUN_CHECK",
  "recordId": "001000000000001AAA",
  "qualifiedApiName": "Account_Name_Required",
  "correlationId": "mcp-request-42"
}

Run one Check Set by changing operation to RUN_CHECK_SET and supplying the exact Check Set QualifiedApiName.

The API rejects unknown JSON fields. It never adds or removes rhc__, retries alternate identities, accepts arbitrary SOQL or Apex, or lets the caller choose event publication. The request body limit is 16,384 bytes.

Completed evaluation

Every completed evaluation uses HTTP 200, including business FAIL, SKIPPED, UNABLE_TO_EVALUATE, and ERROR results. A Check response follows this shape:

{
  "contractVersion": "1.0",
  "correlationId": "mcp-request-42",
  "success": true,
  "operation": "RUN_CHECK",
  "status": "SKIPPED",
  "reasonCode": "VALUE_IS_EMPTY"
}

A Check Set response replaces reasonCode with passed, failed, skipped, unable, and systemError counts. The strongest Set status uses this order:

ERROR -> UNABLE_TO_EVALUATE -> FAIL -> PASS -> SKIPPED

An HTTP client must not treat HTTP 200 alone as a healthy result. Read success, then status and the explicit counts.

Adapter errors

HTTP status	Error type	Meaning
`400`	`VALIDATION`	Invalid JSON, operation, ID, configuration identity, or evaluation selection
`403`	`AUTHORIZATION`	The Salesforce integration principal lacks the run entitlement
`413`	`LIMIT`	Request body exceeds 16,384 bytes
`415`	`VALIDATION`	Content type is not JSON
`500`	`EXECUTION`	An unexpected adapter or evaluator failure prevented completion

Adapter errors return success=false, a safe error type, and a safe message. They do not include a health status, query, formula, stack trace, exception text, record value, token, session ID, or administrator diagnostic.

Limits and security behavior

One request evaluates one record and one exact Check or Check Set.
Event publication is always NONE.
Execution is attributed to AGENT for lifecycle context shared by approved agent and tool callers.
The checked record remains unchanged.
Salesforce user-mode queries and sharing enforce the integration principal’s access.
Record absence and inaccessible data never authorize an elevated comparison query.
Correlation IDs use at most 120 restricted characters and never grant access.

Verification

Before connecting an MCP server, verify these cases in a non-production subscriber-style org:

Namespaced and unpackaged endpoint routes.
One completed response for each of the five statuses.
Exact administrator-created and packaged qualified API names.
Missing run permission, missing record sharing, and missing field access.
Unknown JSON property, operation, and configuration identity.
Wrong content type and oversized body.
Fatal evaluator failure returns a generic HTTP 500 response.
No result event is published and no checked record is modified.