Result contracts - Agents First Docs | Agents First

Start

Overview
Quickstart
Concepts

App Foundations

Workspaces
Access portal

External Agents

External Agents
OAuth and auth.md
MCP
OpenAPI
Result contracts

Internal Agents

Internal Agents
Sales Command

CRM

Contacts
Inbox

Client Delivery

Project rooms

Automations

Lead intake

Billing And Access

Subscriptions

Troubleshooting

Login
Domains

Browse sections

Start

Overview Quickstart Concepts

App Foundations

Workspaces Access portal

External Agents

External Agents OAuth and auth.md MCP OpenAPI Result contracts

Internal Agents

Internal Agents Sales Command

CRM

Is this helpful?

AI tools

Client Delivery

Project rooms

Automations

Lead intake

Billing And Access

Subscriptions

Troubleshooting

Docs/External Agents

Public documentation

Result contracts

How external agents read policy, settlement, impact, MCP isError, and REST 422/202.

Is this helpful?

AI tools

Guarantee tools (P0)

send_sms — contact-policy deny before provider
manage_marketing_email / send_campaign_batch — durable campaign defer (may include partial sends)

MCP advertises outputSchema for these two tools only. Other tools roll out when their runtime results already match the same public schema.

Public fields (schemaVersion: 1)

Canonical page: agentsfirst.ai/docs/external-agents/results

| Field | Meaning | |---|---| | schemaVersion | Always 1 today | | settlement.state | not_started \| committed \| unknown — OperationSpec-boundary receipt for the idempotent command | | policy.decision | allow \| deny \| defer plus code and optional retryAt | | impact | Counts when present (requested / committed / deferred / denied / failed) | | recovery.suggestedNextTool | Often lookup_marketing_campaigns after a marketing defer |

settlement is not the existing wire noun effect (AgentToolEffect).

Batch partial sends + durable hold ⇒ settlement.committed with impact breakdown (sent + deferred in one command).

MCP projections

| Outcome | Shape | |---|---| | Policy deny | tools/call result with isError: true + structuredContent (not a JSON-RPC error) | | Defer / hold | isError: false + settlement/policy/impact — no MCP Task | | Auth / token / scope | JSON-RPC / HTTP 401 or 403 + WWW-Authenticate |

REST projections

| Outcome | Shape | |---|---| | Policy deny | HTTP 422 application/problem+json — type https://agentsfirst.ai/problems/policy-deny — honor retryAt / Retry-After; do not re-authenticate | | Defer / hold | HTTP 202 + body + Retry-After when known — no `Location` (no task monitor) | | Invalid token | HTTP 401 | | Insufficient scope | HTTP 403 + WWW-Authenticate |

Pre-GA: policy deny previously used opaque {ok:false,…} bodies and/or status-line overlap with scope failures. Treat type + Content-Type as authoritative; prefer 422 for policy.

Authenticated OpenAPI: https://app.agentsfirst.ai/api/external-agent/rest/openapi.json (under your grant). Public discovery OpenAPI remains https://agentsfirst.ai/api/openapi.json.

Thin continuity

1. Call manage_marketing_email / send_campaign_batch. 2. Read campaignId from the result (and recovery.suggestedNextTool when present). 3. Disconnect freely. 4. Fresh session: lookup_marketing_campaigns(campaignId) → structured status / counts / updatedAt / next attempt. 5. Agent notes are not authority — always re-query by id.

Same-key replay is safe and will not re-send deferred recipients.

What not to invent

MCP Tasks or REST /tasks monitors for campaigns
Location headers on 202 defer
Treating any HTTP 403 as “reconnect OAuth” when the body is policy-deny