BotSpot: AI Trading, Backtests and Bots

Get broker token refresh status

get_broker_token_refresh_status

Read-onlyIdempotent

Read-only token refresh status for one saved broker credential owned by the authenticated user. Use this after Schwab or Tradier OAuth snapshot runs to verify whether Node persisted rotated token material. In a reconnection conclusion, state the returned snapshotStatus and snapshotVerifiedAt separately from authorizationSavedAt and subsequentRefreshVerifiedAt, with their actual dates. A verified snapshot and a later verified token refresh each establish their own successful check; neither proves that a strategy ran. When an unchanged active schedule is evidenced, describe its next run as scheduled to attempt, with no guarantee. Authorization saved, fresh snapshot verified and a later required refresh verified are separate facts. A historical scheduled skip is not replayed by reconnecting; successful connectivity cannot guarantee the next market-day run. Returns distinct authorizationSavedAt, fresh snapshot verification status/time/error, subsequent required refresh verification time, broker metadata, refresh eligibility, tokenRotationVersion, and sanitized tokenRotationAudit fields such as lastRotatedAt, lastPurpose, and lastRotatedKeyNames. Raw broker credentials, Vault ids, runtime secret ARNs, rotation grant metadata, and secret values are never returned.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "brokerCredentialId": "<brokerCredentialId>"
    },
    "name": "get_broker_token_refresh_status"
  }
}

Input Schema

Name	Required	Description	Default
`brokerCredentialId`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 23, 2026

TDQS

A3.6/5.0

Behavior4/5

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

Annotations already cover read-only, idempotent, non-destructive semantics, and the description adds real value on top: it enumerates what is returned, and explicitly states that raw credentials, Vault ids, runtime secret ARNs, rotation grant metadata and secret values are never returned. It also warns about interpretation limits (a verified refresh does not prove a strategy ran). It stops short of stating auth requirements or rate/error behavior.

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 definition is bloated with repetitive hedging about what facts do and do not prove; several sentences restate the same distinction between saved authorization, verified snapshot, and verified refresh. The valuable content (scope, trigger, returned fields, security exclusions) is buried rather than front-loaded.

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 no output schema, the description carries the return-value burden and does so thoroughly, enumerating snapshotStatus, snapshotVerifiedAt, authorizationSavedAt, tokenRotationVersion and sanitized audit fields. For a single-parameter read tool this is complete enough, with only provenance of the id parameter left implicit.

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

Parameters3/5

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

The single brokerCredentialId has 0% schema description coverage, so the description must compensate. It conveys ownership scoping ('owned by the authenticated user') and implicitly identifies the credential as a saved broker credential, but never says where to obtain the UUID (e.g., list_broker_credentials) or what happens on an unknown id.

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

Purpose4/5

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

States a specific verb and resource: 'Read-only token refresh status for one saved broker credential owned by the authenticated user.' It is clearly narrower than siblings such as get_broker_account_snapshot or list_broker_credentials, though it never names an alternative tool explicitly.

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?

Gives a concrete trigger: 'Use this after Schwab or Tradier OAuth snapshot runs to verify whether Node persisted rotated token material.' That is clear when-to-use context, but there is no when-not guidance or named alternative for the adjacent question of listing or validating credentials.

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

All BotSpot: AI Trading, Backtests and Bots tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.