Skip to main content
Glama

auth_status

Read-onlyIdempotent

Checks Gmail sign-in status, token storage, granted scopes, and validity, reporting when reauthentication is required due to missing or extra scopes without exposing the token.

Instructions

Gmail sign-in status: where the token is stored, granted scopes (checked at startup), validity.

Reports reauth_required when a scope is missing (an old token without gmail.modify: labels and trash blocked, everything else works) or extra: the user must then sign in again. Never shows the token.

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

Input Schema

NameRequiredDescriptionDefault

No arguments

Output Schema

NameRequiredDescriptionDefault
codeNo
errorNo
validNo
expiryNo
scopesNo
statusYes
accountNo
messageNo
presentNo
startupNo
storageNo
warningNo
reauth_requiredNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed16 schema fields changedv0.12.3
    • addedOutput schema / properties / account
      Added value: +{
      +  "title": "Account",
      +  "type": "string"
      +}
    • addedOutput schema / properties / code
      Added value: +{
      +  "title": "Code",
      +  "type": "string"
      +}
    • addedOutput schema / properties / error
      Added value: +{
      +  "title": "Error",
      +  "type": "string"
      +}
    • addedOutput schema / properties / expiry
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "title": "Expiry"
      +}
    • addedOutput schema / properties / message
      Added value: +{
      +  "title": "Message",
      +  "type": "string"
      +}
    • addedOutput schema / properties / present
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "boolean"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "title": "Present"
      +}
    • addedOutput schema / properties / reauth_required
      Added value: +{
      +  "title": "Reauth Required",
      +  "type": "boolean"
      +}
    • removedOutput schema / properties / result
      Removed value: -{
      -  "title": "Result",
      -  "type": "string"
      -}
    • addedOutput schema / properties / scopes
      Added value: +{
      +  "additionalProperties": true,
      +  "title": "Scopes",
      +  "type": "object"
      +}
    • addedOutput schema / properties / startup
      Added value: +{
      +  "additionalProperties": true,
      +  "title": "Startup",
      +  "type": "object"
      +}
    • addedOutput schema / properties / status
      Added value: +{
      +  "title": "Status",
      +  "type": "string"
      +}
    • addedOutput schema / properties / storage
      Added value: +{
      +  "title": "Storage"
      +}
    • addedOutput schema / properties / valid
      Added value: +{
      +  "title": "Valid",
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / warning
      Added value: +{
      +  "title": "Warning",
      +  "type": "string"
      +}
    • changedOutput schema / required
      Previous value: -[
      -  "result"
      -]New value: +[
      +  "status"
      +]
    • changedOutput schema / title
      Previous value: -"auth_statusOutput"New value: +"AuthStatusResult"
  2. First observedv0.1.0

TDQS

A4.3/5.0
Behavior5/5

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses the degraded-mode contract: a missing gmail.modify scope blocks only labels and trash while everything else still works, and reauth_required is the signal for that. It also states the security guarantee that the token itself is never returned, which is exactly the kind of context annotations cannot convey.

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

Conciseness4/5

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

Front-loaded with the core statement and two sentences total, with no filler. The parenthetical explaining the missing-scope case is densely compressed, but every clause carries distinct information.

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

Completeness4/5

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

With an output schema present, the description needn't enumerate return fields, and annotations already cover the safety profile, so the remaining burden is the reauth_required semantics, which is handled. Only the follow-up action after a reauth_required result is left somewhat implicit.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-arg tool applies. The description correctly adds no redundant argument chatter.

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 first clause names a specific resource and the exact facts it reports: token storage location, granted scopes, and validity. None of the 20 siblings (message, thread, label, draft operations) overlap with this diagnostic purpose, so an agent can identify it immediately.

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

Usage Guidelines3/5

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

Usage is only implied: 'checked at startup' and the reauth_required explanation suggest this is a health/diagnostic check to run before mail operations fail. There is no explicit statement of when to call it versus when to skip it, or of what an agent should do after a reauth_required result beyond 'the user must then sign in again.'

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