When to use diagnostic tools

Most agent interactions use the eight primary read tools and the propose_change write tool. Diagnostic tools are for inspecting the system itself: token expiry, draft lifecycle state, audit log entries, and account sync freshness.

You can call diagnostic tools directly from your AI client. Ask the agent "check the token health for my Google Ads account" and it calls check_token_health and returns a structured status.

{check_token_health}

Checks the OAuth token state for a linked ad platform account.

• Returns valid, expiring_soon (within 7 days), or expired for each linked account.
• Includes the platform name, account ID, and the ISO 8601 expiry timestamp.
• If expired, the agent cannot read or draft against that account until you re-authorize via the SpendSignoff dashboard.
• Does not refresh the token itself — token refresh requires user action in the dashboard.

{get_draft_status}

Returns the current lifecycle state of one or more Draft objects by draft ID.

• States: pending_review, approved, rejected, stale, applied, apply_failed, rolled_back.
• A draft enters stale automatically if it was not approved within 48 hours of creation.
• Use this tool to check whether a draft you produced in a previous session has been actioned.
• The agent can list drafts with list_pending_drafts to find IDs before calling get_draft_status.

{list_audit_entries}

Returns KMS-signed audit log entries for a linked account, filtered by time range or operation type.

• Every live change — approved draft applications and rollbacks — has a corresponding signed entry.
• Each entry includes: entry ID, account ID, operator identity (Clerk user ID), operation type, before-value, after-value, ad platform API response status, and ISO 8601 timestamp.
• You can filter by operation_type (e.g., budget_change, bid_change, pause, resume, rollback).
• The log is append-only. Entries cannot be deleted or modified via any MCP tool.

{get_sync_state}

Returns the last-synced timestamp and sync health for each linked account.

• SpendSignoff maintains a local cache of account structure and metrics, refreshed by background sync workers.
• Returns healthy, stale (last sync more than 6 hours ago), or error per account.
• If stale or error, performance data shown by the agent may not reflect the current state in the ad platform.
• Sync errors are also surfaced as anomaly alerts in the SpendSignoff dashboard notifications panel.

{get_loop_status}

Returns the current state of the autonomy loop for each configured rule.

• Shows whether each rule is enabled or disabled, the last evaluation timestamp, and whether a draft was produced in the current 24-hour window.
• If a draft was produced, returns the draft ID so you can check its status with get_draft_status.
• The 24-hour draft limit is a server-side hard cap. The tool accurately reflects whether the loop has fired in the current window.
• In V1, only one rule can be enabled per account at a time. Enabling a second rule automatically disables the first.