jquants-mcp

health_check

Read-onlyIdempotent

Verify server health, API key setup, and cache readiness at session start before J-Quants data calls; also use after timeouts to separate delays from failures.

Instructions

Check server health, API key configuration, and cache readiness.

Offloaded to a worker thread (see _health_check_impl): the body can trigger the slow lazy cache initialization (connect + migrations), and every tool here is async def (the SDK runs those on the event loop; only sync def handlers go to a worker thread, and only since SDK 2.x), so an explicit asyncio.to_thread offload is required here to keep that work off the loop. Sharing the SQLite connection with the loop from that thread is what caused #537; the store's write lock, not this offload, is what makes it safe.

Call this at session start to confirm cache.db has finished loading before issuing detect_* or cache_status — the first call after server start may take 10–60 seconds while the cache initialises lazily. After a tool-call timeout, use this to distinguish a transient cache-loading delay from a permanent failure.

Returns server version, API key status, active plan, status (healthy / degraded), cache_integrity and cache_ready.

status is degraded only when the integrity check reports a failure; there is no error state, since this call does no I/O that can fail.

cache_integrity (ok / pending / not-checked / failed: / error: ) is the integrity check's own result. The last two carry a detail string appended to the prefix, so test them with startswith, not ==. cache_ready is a boolean shorthand: true only when cache_integrity is exactly "ok".

In multi-user mode, returns the authenticated user's plan.

Input Schema

Name	Required	Description	Default
No arguments

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv0.54.0Aug 8, 2026
- removedInput schema / additionalProperties
```
Removed value: -false
```
- addedInput schema / title
```
Added value: +"health_checkArguments"
```
- addedOutput schema / title
```
Added value: +"health_checkDictOutput"
```
First observedv0.43.3May 28, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Goes well beyond the readOnly/idempotent/closed-world annotations: it discloses the 10–60 second lazy cache initialization on first call, that 'status' is degraded only on integrity failure and that there is no error state, and that cache_integrity values must be tested with startswith rather than ==. These are exactly the behaviors an agent cannot derive from structured fields.

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

Conciseness3/5

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

The opening sentence and the usage guidance are well front-loaded, but the middle paragraph is internal implementation chatter — asyncio.to_thread offload, sync vs async handlers since SDK 2.x, SQLite connection sharing, and issue #537 — that does not help an agent select or invoke the tool. That block is filler relative to the agent's task.

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?

Although an output schema exists, the description still covers the essentials: return fields, the healthy/degraded vocabulary, the string-prefix semantics of cache_integrity, the cache_ready shorthand, and the multi-user plan caveat. Timing and failure-mode context is complete for a zero-parameter diagnostic.

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 the baseline is 4. No parameter meaning needs to be conveyed or is missing.

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?

Opens with a specific verb and three concrete resource areas: server health, API key configuration, and cache readiness. It also positions itself against siblings by naming detect_* and cache_status as the calls it gates, so an agent can distinguish it from the rest of the list without opening a schema.

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?

Explicit when-to-use: 'Call this at session start to confirm cache.db has finished loading before issuing detect_* or cache_status,' plus a second triggering condition — 'After a tool-call timeout, use this to distinguish a transient cache-loading delay from a permanent failure.' Both the trigger and the named alternatives are stated, leaving nothing to inference.

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

Deploy Server