Skip to main content
Glama
littlebearapps

Outlook Assistant

by littlebearapps
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

Authentication

auth

Check Microsoft Graph authentication status first, then sign in via device code or browser and complete device-code sign-in.

Instructions

Manage authentication with the Microsoft Graph API. action=status (default) returns the current auth state, refreshing an expired access token while the refresh token is still valid (~90 days); call it first to check before other tools. action=authenticate starts sign-in: method: "device-code" (default, works headlessly) returns a code + URL for the user to visit; method: "browser" uses the local auth server on :3333 (run npm run auth-server first). force: true re-authenticates over an existing valid session. If sign-in reports that OUTLOOK_CLIENT_ID is not configured, ask the user for their Azure Application (client) ID and pass it as clientId. action=device-code-complete finishes device-code sign-in once the browser shows it succeeded. action=about returns server version, configured audience, scope list and other diagnostics. Tokens persist to ~/.outlook-assistant-tokens.json and survive server restarts.

Input Schema

NameRequiredDescriptionDefault
forceNoForce re-authentication even if already authenticated (action=authenticate only)
actionNoAction to perform (default: status)
methodNoAuth method for action=authenticate. device-code (default): no auth server needed, works remotely. browser: traditional OAuth redirect via port 3333.
clientIdNoOptional, action=authenticate only. The user's Azure Application (client) ID (a GUID from the app registration's Overview page). Saved to `~/.outlook-assistant-config.json` and used from then on; it is not a secret. The OUTLOOK_CLIENT_ID environment variable takes precedence when set.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv3.14.1
    • addedInput schema / properties / clientId
      Added value: +{
+  "description": "Optional, action=authenticate only. The user's Azure Application (client) ID (a GUID from the app registration's Overview page). Saved to `~/.outlook-assistant-config.json` and used from then on; it is not a secret. The OUTLOOK_CLIENT_ID environment variable takes precedence when set.",
+  "type": "string"
+}
  2. Addedv3.9.1
  3. Removedv3.9.0
  4. Changed3 schema fields changedv3.7.4
    • addedInput schema / additionalProperties
      Added value: +false
    • changedInput schema / properties / action / enum
      Previous value: -[
-  "status",
-  "authenticate",
-  "about"
-]New value: +[
+  "status",
+  "authenticate",
+  "device-code-complete",
+  "about"
+]
    • addedInput schema / properties / method
      Added value: +{
+  "description": "Auth method for action=authenticate. device-code (default): no auth server needed, works remotely. browser: traditional OAuth redirect via port 3333.",
+  "enum": [
+    "device-code",
+    "browser"
+  ],
+  "type": "string"
+}
  5. First observedv3.4.1

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only say readOnlyHint=false, idempotentHint=false, destructiveHint=false; the description goes well beyond by disclosing token persistence to ~/.outlook-assistant-tokens.json, survival across restarts, the ~90-day refresh-token window, the local auth server port, and the interactive code+URL handoff. It also clarifies the sequence needed to finish device-code sign-in. (Note: the openWorldHint=false annotation sits awkwardly with the described Microsoft Graph sign-in flow, but the description itself is consistent with the mutation/idempotency hints.)

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?

It is long but organized action-by-action and front-loaded with the purpose plus the most important routing instruction ('call it first'). Most sentences carry unique operational detail, though the density is high enough that an agent must parse a multi-clause paragraph rather than scan.

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?

There is no output schema, so the description correctly carries the return-value burden: status returns auth state, about returns version/audience/scopes/diagnostics, authenticate returns a code plus URL. Failure handling (client ID not configured) and setup prerequisites (npm run auth-server) are also covered, leaving no obvious gap for a four-action auth tool.

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 real meaning the schema does not: the default action is status, device-code is the default method, force re-authenticates 'over an existing valid session', and clientId is persisted to ~/.outlook-assistant-config.json with OUTLOOK_CLIENT_ID taking precedence. It also explains the device-code-complete sequencing, which the schema leaves as a bare enum value.

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 description states a specific verb and resource ('Manage authentication with the Microsoft Graph API') and enumerates every action (status, authenticate, device-code-complete, about) with what each returns or initiates. An agent can distinguish this from all 21 email/calendar/contact siblings at a glance, since none of them handle credentials or sessions.

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?

It gives explicit routing: 'call it first to check before other tools' for action=status, device-code vs browser selection ('works headlessly' vs 'run npm run auth-server first'), when to use force:true, and when to ask the user for a client ID. It also names the fallback condition (OUTLOOK_CLIENT_ID not configured) that triggers the clientId parameter.

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

Deploy Server

Other Tools