Check Formation Progress
get_company_onboarding_statusCanonical 'where am I?' entry point — call this ONCE per user session, at the start, right after the OAuth handshake. No arguments required; customerId is read from the bearer. The response's suggestedNextStep (the tool to call next) and nextActionInput (a {tool, arguments} template: call that tool and replace every in arguments with the user's real answer) drive the next call.
DO NOT call this before every formation call. Each formation tool's response already carries nextAction + nextActionInput — trust that and move on. Re-calling get_company_onboarding_status between steps just adds latency and burns rate limit without changing the plan.
Only call this AGAIN when one of these is true: (a) the user returns mid-flow after a long pause and asks 'where are we?', (b) you need to verify state after an unexpected error or a failed call, or (c) the user switched companies via switch_active_company. Outside those cases, treat the first call's state as authoritative for the rest of the session.
Derivation mirrors /web's onboarding routing (Company.gql): each step is marked completed when its corresponding Company / Customer field is populated. If the customer has no active company yet (post-OAuth, pre-formation), the response points at start_formation.
If the response contains error: true or suggestedNextStep looks inconsistent with the user's actual progress (e.g. you just saved the company name but the response steers you back to it), the upstream data fetch likely transiently failed. Wait ~10 seconds and call this tool again before deciding what to do next — do NOT redo earlier steps the user has already completed.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | Optional, for analytics only. In one sentence, why you are calling this tool and how it serves the user's goal. Describe the purpose in general terms: never include names, emails, phone numbers, addresses, IDs or any other personal details. | |
| llm_model | No | Optional, for analytics only. Your exact model identifier from your system prompt (e.g. "claude-opus-4-8"), or "unknown" if unsure. Never guess. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| No | Customer email | ||
| error | No | true if an error occurred | |
| message | No | Human-readable status or instruction | |
| blockers | No | Prerequisites still unmet, in flow order. Same vocabulary as the `missing` array submit_for_review returns. Empty array when formation is fully complete. | |
| lastName | No | Customer last name | |
| companyId | No | Customer's active formation company ID, if any | |
| firstName | No | Customer first name | |
| customerId | No | Customer ID from the OAuth bearer | |
| nextAction | No | Imperative for the agent — follow verbatim. Null when formation is complete. | |
| dashboardUrl | No | URL to doola dashboard | |
| nextQuestion | No | Question to ask the user verbatim before the next formation call. Null when no question is needed. | |
| completedSteps | No | List of steps inferred as completed from the Company / Customer state | |
| nextActionInput | No | {tool, arguments} template for the resume point's call. Replace every <placeholder> in arguments with the user's real answer. Null when formation is complete. | |
| hasActiveSession | No | false if the request was not authenticated (defense in depth) | |
| suggestedNextStep | No | The next formation step to call; null when formation is complete. | |
| countryOfResidence | No | ISO Alpha-3 country code if set |