Skip to main content
Glama

Check Formation Progress

get_company_onboarding_status
Read-only

Canonical '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. Returns the customer's progress: completedSteps, blockers (unmet prerequisites in flow order), suggestedNextStep (the tool for the step the flow waits on), and nextStep ({tool, missingFields, description}) with nextQuestion, all null once formation is complete.

DO NOT call this before every formation call. Each formation tool's response already carries nextStep, so calling this between steps only adds latency and burns rate limit.

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 active company changed through 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), nextStep is start_formation.

If the response contains error: true or nextStep looks inconsistent with the user's actual progress (e.g. the company name was just saved but nextStep is the company name again), 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. Formation flow, in order: start_formation, create_checkout_session, verify_payment, save_company_details (industries from search_industries), submit_formation. Each response's nextStep is the step the flow now waits on.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "get_company_onboarding_status"
  }
}

Input Schema

NameRequiredDescriptionDefault
contextNoOptional, 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_modelNoOptional, for analytics only. Your exact model identifier from your system prompt (e.g. "claude-opus-4-8"), or "unknown" if unsure. Never guess.
conversation_idNoOptional, for analytics only. The exact conversation_id from this server's previous response, unchanged. The first response provides one, so leave this out until you have it and never invent one. Keep passing the same value for the rest of the conversation, even when the user moves on to a new request.

Output Schema

NameRequiredDescriptionDefault
emailNoCustomer email
errorNotrue if an error occurred
messageNoHuman-readable status
blockersNoPrerequisites still unmet, in flow order. Same vocabulary as the `missing` array submit_for_review returns. Empty array when formation is fully complete.
lastNameNoCustomer last name
nextStepNoThe step the formation flow now waits on; null once formation is complete.
companyIdNoCustomer's active formation company ID, if any
firstNameNoCustomer first name
customerIdNoCustomer ID from the OAuth bearer
dashboardUrlNoURL to doola dashboard
nextQuestionNoThe customer-facing question for nextStep; null once formation is complete.
completedStepsNoList of steps inferred as completed from the Company / Customer state
conversation_idNoThis conversation's handle. Pass it unchanged as conversation_id on every later call.
hasActiveSessionNofalse if the request was not authenticated (defense in depth)
suggestedNextStepNoThe tool for the step the flow waits on, as in nextStep; null when formation is complete.
countryOfResidenceNoISO Alpha-3 country code if set
responsiblePartySsnOnFileNoWhether doola has the responsible party's SSN for the EIN application. Only ever this boolean: no tool returns the SSN or any part of it.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changed
    • changedOutput schema / properties / message / description
      Previous value: -"Human-readable status or instruction"New value: +"Human-readable status"
    • removedOutput schema / properties / nextAction
      Removed value: -{
      -  "description": "Imperative for the agent — follow verbatim. Null when formation is complete.",
      -  "type": [
      -    "string",
      -    "null"
      -  ]
      -}
    • removedOutput schema / properties / nextActionInput
      Removed value: -{
      -  "description": "{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.",
      -  "type": [
      -    "object",
      -    "null"
      -  ]
      -}
    • changedOutput schema / properties / nextQuestion / description
      Previous value: -"Question to ask the user verbatim before the next formation call. Null when no question is needed."New value: +"The customer-facing question for nextStep; null once formation is complete."
    • addedOutput schema / properties / nextStep
      Added value: +{
      +  "description": "The step the formation flow now waits on; null once formation is complete.",
      +  "properties": {
      +    "description": {
      +      "description": "Where the customer stands at this step and what their options are.",
      +      "type": "string"
      +    },
      +    "missingFields": {
      +      "description": "Arguments of that tool the step still needs.",
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    "tool": {
      +      "description": "The tool that records this step.",
      +      "type": "string"
      +    }
      +  },
      +  "type": [
      +    "object",
      +    "null"
      +  ]
      +}
    • changedOutput schema / properties / suggestedNextStep / description
      Previous value: -"The next formation step to call; null when formation is complete."New value: +"The tool for the step the flow waits on, as in nextStep; null when formation is complete."
  2. Changed1 schema field changed
    • addedOutput schema / properties / responsiblePartySsnOnFile
      Added value: +{
      +  "description": "Whether doola has the responsible party's SSN for the EIN application. Only ever this boolean: no tool returns the SSN or any part of it.",
      +  "type": "boolean"
      +}
  3. Changed2 schema fields changed
    • addedInput schema / properties / conversation_id
      Added value: +{
      +  "description": "Optional, for analytics only. The exact conversation_id from this server's previous response, unchanged. The first response provides one, so leave this out until you have it and never invent one. Keep passing the same value for the rest of the conversation, even when the user moves on to a new request.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / conversation_id
      Added value: +{
      +  "description": "This conversation's handle. Pass it unchanged as conversation_id on every later call.",
      +  "type": "string"
      +}
  4. First observed

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds substantial behavior beyond readOnly/openWorld/destructive annotations: customerId comes from the bearer, no arguments are needed, repeated calls burn rate limit, the first response is authoritative for the session, and transient failures should be retried after ~10 seconds rather than redoing completed steps. It also explains how completion is derived from populated fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core instruction and then layers call-frequency rules, retry guidance, and flow order in clearly separated paragraphs. Despite its length, every section adds distinct operational guidance and no sentence is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Complete for a complex, stateful onboarding-progress tool: it covers invocation timing, auth source, return semantics, retry behavior, and the ordered formation flow. An output schema exists, so the description does not need to expand further on return structures.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful auth context by stating that no arguments are required and customerId is read from the bearer. It does not elaborate on the optional analytics parameters, which are fully described in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific role ('Canonical where am I? entry point') and names the exact progress data returned: completedSteps, blockers, suggestedNextStep, and nextStep. It also distinguishes itself from the formation-step tools by warning not to call it between steps.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit invocation timing: once per user session right after OAuth, not before every formation call, and only again under three named conditions (returning mid-flow, verifying after an error, or switch_active_company). It also names the overall formation flow so the agent knows when other tools, not this one, should be used.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.