Reference
Agent tool contract
Apply this contract when connecting an Agentforce, REST, or MCP client. Administrators enabling native actions should use Agentforce actions.
Use this contract when a native Agentforce action, Apex REST adapter, or MCP tool evaluates one Record Health Check or Check Set for one Salesforce record.
Boundary
Section titled “Boundary”Version 1 supports two read-only operations:
| Operation | Selection | Records |
|---|---|---|
RUN_CHECK | One exact Check QualifiedApiName | 1 |
RUN_CHECK_SET | One exact Check Set QualifiedApiName | 1 |
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.
Request
Section titled “Request”| Field | Required | Limit | Meaning |
|---|---|---|---|
operation | Yes | Two listed values | Selects the evaluation |
recordId | Yes | 15 or 18 alphanumeric characters | Identifies one record; syntax does not prove access or existence |
qualifiedApiName | Yes | 255 characters | Exact value returned by Salesforce |
correlationId | No | 120 restricted characters | Connects 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.
Successful response
Section titled “Successful response”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.
| Field | Check | Check Set | Limit |
|---|---|---|---|
contractVersion | Yes | Yes | Fixed value 1.0 |
correlationId | Yes | Yes | 120 restricted characters |
success, operation, status | Yes | Yes | Fixed schema values |
reasonCode | Optional | No | 80 characters |
passed, failed, skipped, unable, systemError | No | Yes | Each is 0 through 25 |
diagnosticId | Optional | Optional | 255 characters |
diagnosticCategory | Optional | Optional | 80 characters |
diagnosticSummary | Optional | Optional | 1,000 characters |
recommendedAction | Optional | Optional | 1,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.
Handle adapter errors
Section titled “Handle adapter errors”An adapter failure returns success=false, a safe message of at most 1,000 characters, and one type:
| Error type | Meaning |
|---|---|
AUTHORIZATION | The Salesforce principal cannot start the evaluation |
VALIDATION | The request is malformed, incomplete, names invalid configuration, or targets a Salesforce instance host outside the approved MCP destinations |
LIMIT | The request or response exceeds an enforced boundary |
EXECUTION | An unexpected adapter or platform problem prevented completion |
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.
Identity and sensitivity
Section titled “Identity and sensitivity”The native action uses the configured Agentforce principal’s Salesforce access. 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.
Compatibility and verification
Section titled “Compatibility and verification”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.