Skip to main content
Glama

gflow_auth_status

Probe Flow session status before generation to detect expired auth early without launching an interactive login.

Instructions

Non-interactive, credit-free Flow session probe (#497). Call this BEFORE a generation tool to fail fast on expired auth, before a long blocking generation call. Never starts an interactive login flow. May boot a short-lived headless browser, which on flow.google.com is the usual path, and may take up to ~2 min on a slow network. Every session result also carries wire: {status, build}, the health of the direct (browser-free) credits read, probed first with one GET and one POST to flow.google.com unless the direct read is off. wire.status is accepted (the saved cookies work), signed_out_shell or http_401 (Flow refused the saved session), store_unreadable (the profile's cookies could not be read: Chrome has it open, or it has no saved session), disabled (GFLOW_CLI_WIRE_READS=0 or the macOS default), proxy_configured, throttled, no_chrome_version, network, redirect, http_400, http_error, unparseable or unexpected. With accepted, credit reads need no browser; any other status means they use the browser instead and does not change status, except throttled: Flow is rate-limiting the account, so the browser probe is skipped and the result is status: throttled with a retryable 429 error carrying retry_after seconds. build is Flow's build label when read, else null.

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": "gflow_auth_status"
  }
}

Input Schema

NameRequiredDescriptionDefault
profileNodefault

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A3.7/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does substantial work: it discloses that no credits are consumed, that a short-lived headless browser may be booted, that a call may take ~2 minutes on a slow network, that direct reads issue one GET and one POST to flow.google.com, and that throttling yields a retryable 429 with retry_after. The main weakness is that roughly half the enumerated wire.status values (proxy_configured, network, redirect, http_400, http_error, unparseable, unexpected) are listed without saying what they mean for the caller or what to do next.

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

Conciseness2/5

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

The purpose is front-loaded, but the body is a dense run-on with a 13-value status enumeration, a stray issue reference '(#497)', and nested backticked identifiers that are hard to parse in one pass. Much of the status list adds bulk without explanation, while the genuinely important details (browser fallback behavior, 429/retry_after) are buried in the middle of the paragraph.

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

Completeness3/5

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

An output schema exists, so the lengthy return-value discussion is partly redundant, yet it still omits the key distinction between the tool's top-level `status` field and `wire.status` — only the latter's vocabulary is documented, and even then only a few values are explained. The behavioral picture (cost, latency, auth side effects) is complete enough for a caller, but the parameter and result-field gaps leave real ambiguity.

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

Parameters2/5

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

Schema description coverage is 0% for the single `profile` parameter, and the description never explains what a profile is, what values are valid, or when to pass a non-default one. The only incidental touch is 'the profile's cookies could not be read', which hints that profiles are cookie stores but adds no actionable meaning for invoking the tool with a specific profile.

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?

The opening clause 'Non-interactive, credit-free Flow session probe' names a specific verb (probe) and resource (Flow session), and immediately positions it relative to generation tools ('call this BEFORE a generation tool'). An agent can tell this is an auth/session health check, not a credit read (gflow_get_credits) or a generation call.

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

Usage Guidelines4/5

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

It gives an explicit trigger: call before a generation tool, and specifically before a long blocking generation call, to fail fast on expired auth. It also rules out one behavior ('Never starts an interactive login flow'). It stops short of stating when not to call it (e.g., it is unnecessary if a generation was just successfully performed) or which sibling to prefer for credit counts.

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