AI Tool-Calling Architect — Reliable Agent Actions

Reliable CRM Tool-Calling Design

Scope and evidence

The two supplied signatures are design inputs only. No CRM connection, credentials, API contract, or live system state was provided. Recommendations below are proposals; no tools or changes were executed.

Safer contracts

get_account — Keep read-only. Require a validated account identifier and return a minimal allowlisted record with stable ID, fields, source timestamp, and explicit not-found/forbidden/temporarily-unavailable errors. Enforce user access and tenant scope in the service, not in the model.

create_task — Treat as a side effect. Require account ID, concise title, validated ISO date/time and timezone, owner or queue when needed, and an idempotency key. Reject unknown fields and invalid or unauthorized account references. Return a stable task ID, normalized values, creation status, and correlation ID. Do not accept a caller-supplied identity or bypass server-side authorization.

Execution policy

1. Confirm user intent, task purpose, target account, due date/timezone, and permission to create the task. Read the account only if needed to disambiguate or verify scope.
2. Show a concise preview and request approval before creation unless an explicit, scoped policy already authorizes this class of write.
3. Validate all fields and permissions immediately before the write. Apply least privilege and prevent cross-tenant access.
4. Submit once with an idempotency key derived from the logical request. A timeout after submission is an

unknown outcome, not proof of failure.
5. On ambiguous timeout, query by idempotency key or task ID and reconcile external state before considering another write. Never blindly retry.
6. Verify the resulting task ID, account, title, due date, and status against an authoritative read. Report only what was confirmed.

Error and recovery behavior

• Invalid input: explain the field and ask for correction; do not call the write tool.
• Not found / forbidden: stop and avoid disclosing protected account data.
• Definite pre-execution failure: correct or safely retry according to documented semantics.
• Unknown write outcome: pause, reconcile, and escalate if state cannot be established.

Partial success: preserve correlation IDs, explain what is known, and avoid duplicating effects. Use a documented compensating action only with authorization.

Observability

Record request/correlation ID, user and tenant context, tool and schema version, authorization/approval decision, validated arguments with sensitive fields minimized, result state, idempotency key, verification outcome, and timestamps. Keep secrets and unnecessary customer data out of logs.

User-facing status

Before approval: “I’m ready to create a follow-up task for [account] titled [title], due [date/time and timezone]. Confirm?” After verified success: report task ID and saved details. If the outcome is ambiguous, say it is unconfirmed and that the system is checking; do not say it succeeded or failed until reconciled.

Next evidence needed

Review the actual API schema, permission model, account scoping rules, idempotency support, timeout semantics, error codes, audit/retention policy, and whether user confirmation is required by business policy.