Provides tools for independent, continuous verification of Polygon.io's API accuracy, uptime, and freshness, enabling AI agents to assess data reliability through composite scores and health alerts.
Every API makes promises. OathScore checks the receipts.
The trust layer for AI agents. Two products:
/now — A single endpoint returning the current state of the world for trading agents. Exchange status, volatility, events, regime, data health — one call.
OathScore Ratings — Independent, continuous verification of data API accuracy, uptime, freshness, and reliability. The credit bureau for data APIs.
# What's happening right now?
curl https://api.oathscore.dev/now
# Should I trust this data source?
curl https://api.oathscore.dev/score/curistat
# Compare two sources
curl https://api.oathscore.dev/compare?apis=curistat,alphavantageRelated MCP server: fathom-fyi
{
"mcpServers": {
"oathscore": {
"command": "python",
"args": ["-m", "oathscore_mcp"]
}
}
}Requires: pip install httpx mcp[cli] and clone this repo.
Tool | Description |
| Current world state: exchanges, volatility, events, data health |
| Open/close status for 7 exchanges with next transition times |
| VIX, VIX9D, VIX3M, VVIX, SKEW, term structure |
| Next event, FOMC/CPI countdowns, week high-impact count |
| OathScore rating for a specific API (0-100 composite + grade) |
| Side-by-side comparison of two or more data APIs |
| Active degradation alerts for monitored APIs |
| Service health and data freshness |
For each rated API:
Metric | Weight | How Measured |
Accuracy | 35% | Compare forecasts/claims to actual outcomes daily |
Uptime | 20% | Synthetic monitoring every 60 seconds |
Freshness | 15% | Is "real-time" actually real-time? |
Latency | 15% | P50/P95/P99 from multiple regions |
Schema stability | 5% | Detect breaking changes |
Documentation | 5% | OpenAPI spec, llms.txt, examples |
Trust signals | 5% | Published accuracy data, response signing |
API | Category | Score | Status |
Curistat | Futures volatility | -- | Monitoring |
Alpha Vantage | Equities/macro | -- | Monitoring |
Polygon.io | Market data | -- | Monitoring |
Finnhub | Multi-asset | -- | Monitoring |
Twelve Data | Market data | -- | Monitoring |
EODHD | Historical data | -- | Monitoring |
Financial Modeling Prep | Fundamentals | -- | Monitoring |
Scores populate after 30 days of monitoring data.
/llms.txt — Agent-readable product description
/llms-full.txt — Complete endpoint documentation
/.well-known/ai-plugin.json — ChatGPT plugin manifest
/openapi.json — OpenAPI 3.0.3 spec
/docs — Interactive Swagger UI
Tier |
| Score Queries | Price |
Free | 10/day | 5/day | $0 |
Founding (first 50) | 5,000/day | 2,500/day | $9/mo (lifetime) |
Pro | 10,000/day | 5,000/day | $29/mo |
Enterprise | 100,000/day | 50,000/day | $99/mo |
Pay-per-request (x402) | Unlimited | Unlimited | $0.001-0.005/call |
x402 micropayments: No signup needed. Agents pay per request with USDC stablecoins via the x402 protocol. When rate limited, the API returns 402 Payment Required with payment instructions.
API audits: Independent 7-day quality audit of your API — $299-499. Contact us.
[Monitoring Service - Railway $5/mo]
Every 60s: ping all rated APIs (uptime, latency)
Every 5m: check data freshness
Every 1h: record forecast snapshots
Every 24h: compare forecasts to actuals (accuracy)
Store: Supabase (free tier)
[/now Endpoint - Cloudflare Workers $0/mo]
Every 60s: fetch VIX, compute exchange status, read events
Serve: cached JSON, max-age=30, ETag support
[Scoring Engine - Cloudflare Workers $0/mo]
Every 5m: recompute composite scores from raw metrics
Serve: /score, /compare, /alerts endpointsfrom crewai import Agent, Task
from crewai_tools import MCPTool
# Connect to OathScore MCP
oathscore = MCPTool(server_command="python -m oathscore_mcp")
analyst = Agent(
role="Market Analyst",
tools=[oathscore],
goal="Assess current market conditions before trading"
)
task = Task(
description="Check if markets are open and get current volatility regime",
agent=analyst
)from langchain_mcp import MCPToolkit
toolkit = MCPToolkit(server_command="python -m oathscore_mcp")
tools = toolkit.get_tools()
# Use in any LangChain agent
from langchain.agents import initialize_agent
agent = initialize_agent(tools, llm, agent="zero-shot-react-description")
agent.run("What's the current VIX level and are US markets open?")import httpx
# World state in one call
now = httpx.get("https://api.oathscore.dev/now").json()
print(f"VIX: {now['volatility']['vix']}")
print(f"CME: {'OPEN' if now['exchanges']['CME']['is_open'] else 'CLOSED'}")
print(f"Next event: {now['events']['next_event']}")
# API quality check before committing to a data source
score = httpx.get("https://api.oathscore.dev/score/polygon").json()
if score.get("composite_score", 0) < 70:
print("Warning: data source quality below threshold")Add to your MCP config (~/.claude/mcp.json or Claude Desktop settings):
{
"mcpServers": {
"oathscore": {
"command": "python",
"args": ["-m", "oathscore_mcp"]
}
}
}Then ask Claude: "What's the current market state?" or "How reliable is Alpha Vantage?"
If this is useful, star the repo — it helps others find it.
Proprietary. All rights reserved.
Check OathScore service health and data freshness.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure, but it only says 'check health and data freshness.' It does not indicate whether the operation is read-only, idempotent, or has any side effects. Although a health check is typically safe, the description should explicitly state that it is safe and non-destructive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no extraneous information. Every word is meaningful and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple health check tool with no parameters and an output schema, the description is minimally adequate. However, it could be improved by specifying what 'data freshness' means or how the health status is represented. The presence of an output schema partially compensates, but additional context would help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters in the input schema, and schema description coverage is 100% (trivially). The description does not need to add parameter details. Baseline for 0 params is 4, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: checking OathScore service health and data freshness. It uses a specific verb-resource combination ('Check OathScore service health') and is distinct from sibling tools that deal with APIs, alerts, events, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description only states the function without context for selection, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare quality scores of two or more APIs side-by-side. Pass comma-separated names, e.g. 'polygon,twelvedata'.
| Name | Required | Description | Default |
|---|---|---|---|
| apis | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It doesn't mention any behavioral aspects beyond comparing scores (e.g., if it's read-only, requires auth, or has rate limits). However, the operation is inherently non-destructive, and the description adds the input format detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence plus a brief example, conveying all necessary information without waste. It is front-loaded with the purpose and immediately useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no nested objects, output schema present), the description covers the what and how completely. The example clarifies the expected format. No further details are needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema only defines 'apis' as a string type. The description adds crucial meaning by specifying it expects comma-separated names and gives an example (e.g., 'polygon,twelvedata'). This compensates for the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it compares quality scores of multiple APIs side-by-side, which matches the tool name. It distinguishes from sibling tools like get_score (which likely returns a single score) or check_health.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to pass comma-separated names and provides an example. While it doesn't mention when to use alternatives, the purpose is straightforward and the sibling tools have distinct functions, so it's clear when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get active degradation alerts for monitored APIs. Shows uptime drops, high latency, and schema changes.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must fully disclose behavior. It explains the tool fetches active alerts but lacks details on data freshness, retrieval scope, or authentication needs. Minimal behavioral insight.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the verb and resource. No redundant words; each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and presence of output schema, description adequately covers the tool's purpose and alert categories. Could benefit from mentioning temporal scope (e.g., current alerts only) but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has no parameters (100% coverage). Description correctly avoids adding parameter details. Baseline for zero parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it retrieves active degradation alerts for monitored APIs, listing specific alert types (uptime drops, high latency, schema changes). Distinct from siblings that cover health checks, comparisons, or event retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage for degradation alerts, but no explicit comparison to sibling tools or when-not-to-use. Does not mention alternative tools for similar tasks like check_health.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get economic event countdowns: next event, today remaining, week high-impact count, days until FOMC and CPI.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only describes the output types without detailing side effects, permissions, rate limits, or whether the operation is read-only. For a tool with no annotations, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that clearly front-loads the purpose and lists specific outputs. Every part is necessary and there is no redundancy or verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and an output schema exists (not detailed here, but referenced), the description covers the core purpose and return types. However, it lacks any usage context or caveats, which for a simple tool is acceptable but not maximally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so schema coverage is trivially 100%. According to guidelines, baseline is 4. The description adds meaning by specifying what the tool returns, which goes beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's verb ('Get') and resource ('economic event countdowns') and enumerates specific outputs (next event, today remaining, week high-impact count, days until FOMC and CPI). This distinguishes it from sibling tools like get_score or get_volatility, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for obtaining economic event countdowns but does not explicitly state when to use this tool versus alternatives such as get_alerts or get_now. No exclusions or context about when not to use it are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get open/close status for CME, NYSE, NASDAQ, LSE, EUREX, TSE, HKEX with next transition times.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose behavioral traits such as read-only nature, rate limits, or authentication needs. It only states the output, leaving the agent uninformed about side effects or constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the most important information (purpose and specific exchanges). Every word earns its place; no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and an existing output schema, the description sufficiently defines the tool's purpose and covered exchanges. No additional details are needed for a simple status-check tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so baseline score is 4. The description does not need to add parameter information; it correctly omits any param details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool gets open/close status for specific exchanges (CME, NYSE, NASDAQ, etc.) with next transition times, using a specific verb and listing distinct resources. This differentiates it from siblings like get_volatility or get_score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The description implies usage for exchange status queries but lacks context on when not to use it or mention of sibling tools for related data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current world state: exchange status, volatility (VIX/VVIX/SKEW/term structure), economic event countdowns, and data health. One call replaces 4-6 separate API calls.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It only describes the data returned but does not mention whether the tool is read-only, requires authentication, has rate limits, or any side effects. This is a significant gap for a tool that presumably makes multiple backend requests.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, each earning its place. The first front-loads the purpose with clear noun phrases, and the second quantifies the value proposition. No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, no annotations, and an output schema present (so return values are documented elsewhere), the description adequately covers the tool's purpose and scope. It lists the categories of information retrieved, which is sufficient for a parameterless combined-fetch tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters and 100% schema coverage, so the description does not need to add parameter details. The description adds value by explaining what the tool returns (exchange status, volatility, economic events, data health), which is helpful beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a composite of current world state data: exchange status, volatility metrics, economic event countdowns, and data health. The phrase 'One call replaces 4-6 separate API calls' distinguishes it from sibling tools like get_exchanges or get_volatility which are individual endpoints.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states this tool replaces multiple separate API calls, indicating it should be used for a broad overview. However, it does not mention when NOT to use it or provide explicit alternatives, relying on the implied context that siblings exist for specific subsets.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get OathScore quality rating for a specific API. Available APIs: alphavantage, polygon, finnhub, twelvedata, eodhd, fmp, fred, coingecko, alpaca, yfinance. Returns composite score (0-100), letter grade, and component breakdown.
| Name | Required | Description | Default |
|---|---|---|---|
| api_name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden. It discloses return values (composite score, grade, breakdown) and available APIs, but omits details like caching, authentication needs, or real-time behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise, front-loaded sentences with no redundancy. Every sentence provides essential information without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one parameter and an output schema, the description covers purpose, inputs, and outputs adequately. It lacks explanation of the component breakdown, but the output schema likely fills that gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description adds meaning by listing acceptable API names (alphavantage, polygon, etc.), which the schema lacks. However, it does not specify format or validation beyond the list.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'OathScore quality rating', and specifies the target API. It lists available APIs, distinguishing it from sibling tools like compare_apis or get_alerts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when needing a quality rating for a specific API, but lacks explicit guidance on when not to use this tool or how it compares with siblings like compare_apis. No exclusions or context are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current volatility readings: VIX, VIX9D, VIX3M, VVIX, SKEW, and term structure (contango/backwardation/flat).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It only lists outputs without disclosing behavioral traits like update frequency, rate limits, or error behavior. As a read tool, the lack of transparency is a gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the action and lists key outputs. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema, the description sufficiently covers the tool's purpose and outputs. Minor improvement could include clarifying the data type (e.g., numerical values) but is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters; schema coverage is trivially 100%. The description adds no parameter details because none are needed, meeting the baseline for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it retrieves current volatility readings and lists specific indices and term structure. It clearly identifies the resource and differentiates from sibling tools like get_alerts or get_exchanges.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for fetching volatility data but does not provide explicit guidance on when to use it versus alternatives, nor does it mention when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0check_healthcompare_apisget_alertsget_eventsget_exchangesget_nowget_scoreget_volatilityScored across 8 tools
Each tool has a clearly distinct purpose: health check, API comparison, alerts, events, exchanges, combined state, score retrieval, and volatility. No overlapping functionality.
All tool names follow a consistent verb_noun pattern with snake_case (e.g., get_score, check_health). Conventions are uniform across all 8 tools.
With 8 tools, the server is well-scoped for monitoring API quality and financial market data. Each tool provides distinct value without being overly numerous or sparse.
Core operations are covered: score retrieval, comparison, health, alerts, volatility, exchanges, events, and a combined view. Minor gaps like historical trends or API management are absent but not critical for the stated purpose.
Calibrated world model for AI agents. 40 tools: world state, markets, trading. Kalshi + Polymarket.
Macroeconomic and FX time-series data for AI agents: indicators, calendars, COT, forex, commodities.
Market intelligence for the AI agent economy: rankings, trust signals, liveness. 13 tools.
Market intelligence for AI agents. Real-time data, cross-market analysis, and regime detection.
