Skip to content

Agent tool contract

Reference5 min read

Look up the version 1 request and response contract shared by the Record Health Check Agentforce actions, the Apex REST endpoint, and the MCP server tools, each of which evaluates one Check or Check Set for one Salesforce record. To set them up, see Agentforce actions and Agent tool REST API.

Version 1 supports two read-only operations:

OperationSelectionRecords
RUN_CHECKOne exact Check QualifiedApiName1
RUN_CHECK_SETOne exact Check Set QualifiedApiName1

The contract excludes record updates, arbitrary SOQL, arbitrary Apex, metadata changes, batch evaluation, raw administrator diagnostics, event-publication choice, MCP prompts, and MCP resources. Its schemas are request.schema.json and response.schema.json.

FieldRequiredLimitMeaning
operationYesTwo listed valuesSelects the evaluation
recordIdYes15 or 18 alphanumeric charactersIdentifies one record; syntax does not prove access or existence
qualifiedApiNameYes255 charactersExact value returned by Salesforce
correlationIdNo120 restricted charactersConnects approved operational evidence without carrying record data

Adapters reject unknown fields. They never add or remove rhc__, retry an alternate name, or accept a label in place of the exact qualified API name. Adapters use event publication NONE so a model cannot create events by choosing an argument.

A completed evaluation returns success=true for all five health statuses. FAIL is a business finding. UNABLE_TO_EVALUATE and ERROR do not prove that a record is healthy.

FieldCheckCheck SetLimit
contractVersionYesYesFixed value 1.0
correlationIdYesYes120 restricted characters
success, operation, statusYesYesFixed schema values
reasonCodeOptionalNo80 characters
passed, failed, skipped, unable, systemErrorNoYesEach is 0 through 25
diagnosticIdOptionalOptional255 characters
diagnosticCategoryOptionalOptional80 characters
diagnosticSummaryOptionalOptional1,000 characters
recommendedActionOptionalOptional1,000 characters

Structured fields are the source of truth. Transport-specific prose cannot change or conceal their meaning. The four diagnosis fields are bounded, disclosure-safe guidance for a completed evaluation; they are not raw logs or administrator-only diagnostics.

The diagnosis fields appear when a Check returns UNABLE_TO_EVALUATE or ERROR. For a Check Set, they describe the first such Check. diagnosticId identifies the incident in the Log event and debug log, diagnosticSummary is a fixed one-sentence explanation, and recommendedAction is the first recommended fix. Neither text field contains record values, queries, or formulas. Route on diagnosticCategory:

diagnosticCategoryWhat prevented a verdictWho usually fixes it
ACCESSThe running principal cannot read a field or record the Check needsSecurity administrator
CONFIGURATIONA Check setting is invalid or unavailableAdministrator
FORMULAA formula is invalid, returned the wrong type, or depends on unavailable dataAdministrator
QUERYA query, its token values, its schema, or its result shape could not be usedAdministrator
LIMITThe evaluation reached or approached a Salesforce transaction limitAdministrator; retrying can succeed
APEX_CONFIGURATIONThe Apex Class name or Apex Parameters (JSON) does not resolve to a usable custom Apex CheckAdministrator or developer
APEX_RESULTA custom Apex Check reported that it could not reach a verdictAdministrator
APEX_CONTRACTA custom Apex Check returned an invalid result or attempted a prohibited side effectDeveloper
APEX_EXCEPTIONA custom Apex Check threw an unhandled exceptionDeveloper
FRAMEWORKAn unexpected Record Health Check failure; retry once, then report the diagnosticIdPackage maintainer

An adapter failure returns success=false, a safe message of at most 1,000 characters, and one type:

Error typeMeaning
AUTHORIZATIONThe Salesforce principal cannot start the evaluation
VALIDATIONThe request is malformed, incomplete, names invalid configuration, or targets a Salesforce instance host outside the approved MCP destinations
LIMITThe request or response exceeds an enforced boundary
EXECUTIONAn unexpected adapter or platform problem prevented completion

The REST endpoint checks the Record Health Check Run permission before reading the request body, so its HTTP 403 AUTHORIZATION response carries a correlation ID generated by the server, not the caller’s. The MCP server keeps the AUTHORIZATION error type, returns its own request’s correlation ID with a generic safe message, and does not retry a permission denial. Every other response must carry the caller’s correlation ID. Agentforce actions do not cross this HTTP boundary.

To verify this, call each tool as a non-production user who has access to the REST class but lacks the Run permission. Expect success=false, errorType=AUTHORIZATION, a correlation ID, and no health status. Then restore the user’s permissions and confirm that a known passing Check returns its normal result.

An adapter failure has no health status or completed-evaluation diagnosis. It cannot include a stack trace, query, formula, token, session ID, unrestricted exception, record field value, or administrator diagnostic.

The Agentforce actions use the Salesforce access of the agent’s user: the signed-in user for an employee agent, or the agent user for a service agent. MCP uses a dedicated Salesforce integration principal. MCP client credentials do not delegate the conversational user’s identity, so results can differ when principals have different object, field, sharing, restriction- rule, or scoping-rule access.

Version 1 can return contract version, correlation ID, success, operation, status, reason code, Check Set counts, the four optional bounded diagnosis fields, error type, and a safe error message. It excludes found and expected values, display messages, action URLs, serialized Apex results, queries, formulas, user IDs, raw logs, and administrator diagnostics.

Adding a required field, operation, output data, multi-record input, identity flow, or changed status meaning requires a reviewed contract version and compatibility plan.

Validate integration requests and responses against the linked JSON schemas. Test malformed inputs, missing permissions, and each health status before enabling an integration.