Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@starwell-mcp What's the latest US CPI inflation rate from BLS?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Starwell is the verified data layer for AI: official statistics from Statistics Canada, FRED, the U.S. Bureau of Labor Statistics, the World Bank, SEC EDGAR, the U.S. Treasury, the European Central Bank, the UK Office for National Statistics, INSEE (France), the Australian Bureau of Statistics, the OECD, Eurostat, INE (Spain), the Czech National Bank, ILOSTAT, Statistics Netherlands, the CDC, Statistics Sweden, Statistics Norway, Statistics Finland, Statistics Austria, the Department of Statistics Malaysia, the U.S. Bureau of Economic Analysis, the Central Statistics Office of Ireland, Statistics Denmark, Statistics Poland, Statistics Estonia, Statistics Iceland, and the U.S. Bureau of Transportation Statistics, served as MCP tools. Every observation carries provenance, every series carries a verification status backed by golden-value checks against the live source, and the answer tool returns computed results cited to the official table.
This package is a thin stdio bridge to the Starwell remote MCP server. The tool surface always matches the server, so new sources and tools appear without a package update.
Tools (12): search_catalog, list_sources, list_datasets, get_series, get_series_stats, get_observations, factory_status, answer, deep_analysis, create_monitor, list_monitors, delete_monitor. Reads are open; answer, deep_analysis, and the monitor tools need a free API key (STARWELL_API_KEY).
Remote-capable clients can skip this package and add the URL directly: https://starwell.dev/api/starwell/mcp (Streamable HTTP).
claude mcp add --transport http starwell https://starwell.dev/api/starwell/mcp
# or via stdio:
claude mcp add starwell -- npx -y starwell-mcpSettings, Connectors, Add custom connector, URL https://starwell.dev/api/starwell/mcp. On plans without remote connectors, use the desktop config:
{
"mcpServers": {
"starwell": { "command": "npx", "args": ["-y", "starwell-mcp"] }
}
}.cursor/mcp.json:
{
"mcpServers": {
"starwell": { "command": "npx", "args": ["-y", "starwell-mcp"] }
}
}~/.codex/config.toml:
[mcp_servers.starwell]
command = "npx"
args = ["-y", "starwell-mcp"]~/.gemini/settings.json:
{
"mcpServers": {
"starwell": { "httpUrl": "https://starwell.dev/api/starwell/mcp" }
}
}Settings, Apps, enable developer mode, add connector with the remote URL above.
Related MCP server: mcp-fred
STARWELL_MCP_URL: override the endpoint (staging, self-hosted).
STARWELL_API_KEY: Bearer key from https://starwell.dev/account (free). Data reads work without one; answer, deep_analysis, and monitors require it.
Only openly licensed official sources are served, each with its license and attribution in every response. The set covers U.S. federal statistical works (public domain), the Statistics Canada Open Licence, World Bank CC BY-4.0, and the respective open licences of the ECB, OECD, ONS, INSEE, and ABS. This product uses the FRED API but is not endorsed or certified by the Federal Reserve Bank of St. Louis.
Docs: https://starwell.dev/docs
This repository is the source of the starwell-mcp
npm package. It is generated from Starwell's main repository, so pull requests here
may be applied upstream by hand — but issues are read and very welcome.
The flagship: ask a natural-language question about the served official statistics. Returns a COMPUTED answer (real Python runs in a sandbox over the verified store, nothing is estimated by a model), the Plotly chart, the Python code, citations to the official tables, and a verification badge per series. CROSS-SOURCE: one question may join series from DIFFERENT agencies, e.g. unemployment from the US BLS, Statistics Canada and the UK ONS in a single call, for correlations, ratios, and like-for-like comparison. How many series one question may join is set by the caller's plan; asking for more returns a series_limit error naming that cap. Returns a refusal when no served series can answer. Takes 10-40 seconds. Requires a free API key (create at /account on the Starwell host; pass Authorization: Bearer dlk_... or set STARWELL_API_KEY on the starwell-mcp bridge). Keyless calls return key_required.
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | YYYY-MM-DD | |
| start | No | YYYY-MM-DD | |
| series | No | Optional: pin exact series, across sources, and skip AI resolution | |
| question | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the minimal annotations by disclosing that answers are computed via real Python in a sandbox, that nothing is model-estimated, that calls take 10-40 seconds, that refusals occur when no series can answer, and that keyless calls return key_required. It also exposes plan-based limits and the series_limit error.
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 dense but every sentence earns its place, covering purpose, behavior, outputs, limits, latency, and authentication. Front-loaded with the core purpose, then structured around key behaviors like CROSS-SOURCE, errors, refusal, and key requirements.
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?
Despite having no output schema, the description enumerates what the caller will receive: computed answer, Plotly chart, Python code, citations, and verification badges. It also covers failure modes, latency, plan limits, and authentication, making the tool callable without guessing.
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?
With 75% schema description coverage, the schema already documents start, end, and series. The description adds useful semantics for question ('natural-language question') and series (cross-source joining, plan limits, series_limit error), though it does not expand on start/end beyond the 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 opens with a specific verb and resource: 'ask a natural-language question about the served official statistics.' It distinguishes this tool from data-retrieval siblings by emphasizing computed answers, Plotly charts, code, citations, verification badges, and cross-source joins.
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 makes the intended use clear: use this tool for natural-language analytical questions, especially cross-source comparisons. It does not explicitly name alternatives or state when not to use it, but the 'flagship' framing plus the contrast with raw series retrieval tools gives strong contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a monitor: when the store's refresh lands a new period or a revised value for the series, a series.updated webhook fires to your URL with the new value, verification status, and citation. Requires an API key (free with an account at /account); webhook must be https. Manage with list_monitors / delete_monitor.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | Source slug, e.g. 'fred' | |
| seriesId | Yes | Series id, e.g. 'DGS10' | |
| webhookUrl | Yes | https URL to receive series.updated events |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the readOnlyHint/idempotentHint annotations by disclosing authentication requirements, the https constraint, the trigger condition, and the webhook payload contents (new value, verification status, citation). This gives an agent meaningful operational context for a write operation.
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 concise and well-structured: it front-loads the core action, explains the behavior, lists requirements, and points to related tools—all in three focused sentences with no 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?
For a simple three-parameter creation tool with no output schema, the description covers purpose, trigger behavior, payload, authentication, protocol, and lifecycle management via siblings. Nothing essential for correctly invoking the tool is missing.
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 already fully documents all three parameters with descriptions and examples. The description reinforces that webhookUrl must be https and clarifies what the webhook carries, but it does not add substantial parameter-level semantics beyond the schema. Baseline 3 applies given 100% 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?
Description opens with 'Create a monitor' and states exactly what the tool does: a series.updated webhook fires to the user's URL when the store's refresh lands a new period or revised value. It also distinguishes itself from list_monitors and delete_monitor by mentioning management via those siblings.
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 clearly conveys the intended use case: monitor a series and receive webhook notifications on updates. It also states prerequisites (API key, https webhook) and points to list_monitors/delete_monitor for management. It does not explicitly discuss alternatives like polling or when not to use this tool, but the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The moat: a PLANNED multi-section report on a question. The engine designs 3-4 orthogonal analyses (trend, statistics, outliers, cross-series relationships), runs real Python for each in the sandbox over the verified store, and synthesizes one decision-ready report. Every number computed, every series cited and verification-badged. Sections can join series from DIFFERENT agencies in one report, up to the caller's plan width; over it, the call returns a series_limit error naming that cap. Slower than answer (60-180 seconds), so use it for "analyze", "break down", "give me a full picture" asks; use the answer tool for a single direct question. Requires a free API key (create at /account on the Starwell host; pass Authorization: Bearer dlk_... or set STARWELL_API_KEY on the starwell-mcp bridge). Keyless calls return key_required.
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | YYYY-MM-DD | |
| start | No | YYYY-MM-DD | |
| series | No | Optional: pin exact series, across sources, and skip AI resolution | |
| question | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the sparse annotations: it explains execution in the sandbox, verification badges, cross-agency series joining, slower latency (60-180 seconds), error responses, and API key requirements. There is no contradiction with `readOnlyHint: false`.
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?
Every sentence earns its place: core behavior, output characteristics, error behavior, routing guidance, and auth requirements. The description is dense but well-structured and front-loads what the tool is before diving into operational constraints.
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 complex tool with no output schema, the description covers what matters: the report nature, verification, the sandbox execution model, latency, error cases, and authentication. An agent has enough information to select, invoke, and interpret the result of this 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?
Schema coverage is 75%, so the description still carries some parameter burden. It clarifies the `question` parameter through example phrasings and explains `series` behavior via cross-agency joining and plan-width limits. It does not add detail on `start`/`end` defaults, but the schema already documents their format.
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 a specific capability: a planned multi-section report with 3-4 orthogonal analyses computed via real Python in the sandbox over verified data. It also distinguishes itself from the `answer` sibling by latency and use-case phrasing, so an agent can tell which tool fits.
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?
It gives explicit trigger phrases ('analyze', 'break down', 'give me a full picture') and explicitly says to use `answer` for a single direct question. It also discloses the series_limit error for exceeding plan width and the key_required error for missing auth, giving clear routing and failure guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Monitor id from list_monitors |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Observation values for one series. Every value carries provenance (the exact source URL it came from, retrieval time, connector version) and the envelope carries the series verification status + citation. Defaults to the latest 60 points; use start/end (YYYY-MM-DD) or latest to control the window.
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | YYYY-MM-DD inclusive upper bound | |
| start | No | YYYY-MM-DD inclusive lower bound | |
| latest | No | Return only the latest N points (default 60 when no start/end given) | |
| source | Yes | ||
| seriesId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds meaningful behavioral detail beyond that: every value carries provenance (source URL, retrieval time, connector version) and the envelope includes verification status and citation, which helps set expectations for the return payload.
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 with no redundancy. The core purpose is front-loaded, and the window-control behavior is placed within the same compact description.
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 output schema, the description does a good job of summarizing the return shape (values with provenance, envelope with verification/citation). It is adequate for a read-only retrieval tool, though it omits details like ordering, error cases, or how source relates to seriesId.
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?
Schema coverage is 60%, so the description is not the sole source of parameter meaning. It adds useful window-control semantics ('defaults to the latest 60 points' and 'start/end (YYYY-MM-DD)') but says little about the required source and seriesId parameters beyond implying 'one series'.
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 returns observation values for one series, with a specific resource ('observations') and a scope ('one series'). It does not explicitly contrast with related tools like get_series or get_series_stats, so it stops short of full sibling differentiation.
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 gives concrete usage context: defaults to the latest 60 points and explains how to control the window using start/end or latest. It does not mention when to prefer this tool over siblings, but the window-control guidance is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full metadata for one series: indicator, unit, frequency, geography, coverage, its VERIFICATION STATUS (passing/stale/failing/unverified from golden-value + freshness checks against the live source), recent check records, and the citation to the official table.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | Source slug, e.g. 'fred' | |
| seriesId | Yes | Source-native series id, e.g. 'UNRATE' or 'v41690973' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds meaningful context by explaining that verification status comes from golden-value and freshness checks against the live source. This reveals live comparison behavior beyond static metadata lookup and does not contradict the annotations.
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 leads with the core function ('Full metadata for one series') before enumerating contents. Every element earns its place with no filler or redundancy.
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?
With no output schema, the description thoroughly enumerates return contents (fields, verification status, recent checks, citation), giving an agent a solid understanding of the result shape. It could mention error handling or unknown-series behavior, but coverage is strong for a read-only metadata tool with two documented parameters.
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?
Both parameters are fully described in the schema with concrete examples ('fred', 'UNRATE', 'v41690973'), so schema coverage is 100%. The description adds no parameter-level details beyond that, warranting the baseline score of 3.
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 specifies a unique resource ('metadata for one series') and a clear action, then enumerates the payload components (indicator, unit, frequency, geography, coverage, verification status, check records, citation). This clearly differentiates it from siblings like get_observations and get_series_stats without requiring schema inspection.
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 metadata and verification retrieval, giving clear context for when to use it. However, it does not explicitly state when not to use it or name alternatives such as get_observations for data points, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Latest value, previous, all-time min/max, mean, and change vs the previous period and vs a year ago — computed over the verified store, with the citation attached. The cheap way to answer "what is it now and how has it moved" without a full analysis run.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | Source slug, e.g. 'fred' | |
| seriesId | Yes | Series id, e.g. 'DGS10' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only. The description adds useful behavioral context: results are computed over the 'verified store,' a citation is attached, and the operation is cheap. These details go beyond the raw readOnlyHint and help set expectations about provenance and cost.
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 output contents and followed by a concise usage rationale. No filler or repetition of schema details; every clause earns its place.
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?
There is no output schema, so the description carries the burden of explaining what is returned, and it does so by enumerating the statistics and citation. It leaves minor ambiguity about exact response structure but is complete enough for a simple, read-only stats 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?
Schema coverage is 100%, with both parameters described and exemplified. The tool description does not add new meaning about source or seriesId, but it clarifies that these parameters identify the series whose statistics are returned. This is adequate but not additive.
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 names the exact resource (a series) and the specific statistics returned: latest, previous, min/max, mean, and comparisons. It also distinguishes itself from heavier analysis by billing itself as the 'cheap way' to answer a focused question, separating it clearly from deep_analysis.
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 frames when to use it: for quickly checking current value and movement 'without a full analysis run.' It does not name sibling alternatives like get_observations, but the use case and cost framing give an agent enough context to select this tool over a heavier analysis.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the datasets (official releases/tables) available in one source, with coverage dates and links to the official table pages.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | Source slug, e.g. 'fred' or 'statcan' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already covers the safety profile, and the description adds useful output expectations (coverage dates and links to official pages). However, it does not disclose potential pagination, volume limits, or behavior for sources with no datasets; these are minor gaps given the read-only nature.
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, focused sentence with no filler or redundant restatement of the tool name. It front-loads the primary action and resource, then appends the key output details efficiently.
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 only one fully documented required parameter, no output schema, and a readOnlyHint annotation, the description provides sufficient context: what is returned, the scope, and the source input. An agent can correctly select and invoke this tool without missing critical information.
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 fully documents the single 'source' parameter, including an example format ('fred' or 'statcan'). The description reinforces that the tool is scoped to one source but adds no new parameter-level meaning beyond what the schema already provides.
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 uses a specific verb ('List') and identifies the exact resource ('datasets (official releases/tables)') scoped to a single source, which distinguishes it from siblings like list_sources and search_catalog. It also clarifies the output contents: coverage dates and links to official pages.
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 clearly indicates that this tool is for listing datasets within one source, and references 'official releases/tables' to set expectations. It does not explicitly name alternatives or exclusions, but the scope is clear enough that an agent can decide when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Monitors on your API key, with delivery health (last fired, failures, active).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already signals safety, and the description adds useful behavioral detail by naming the delivery health fields returned (last fired, failures, active). It does not contradict annotations and gives the agent a concrete sense of what the operation reports.
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?
A single, well-structured sentence immediately states the resource and API-key scope, then adds the most useful output detail. Every word earns its place and there is no redundant phrasing.
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 zero-parameter, read-only list tool, the description covers the key information: what is listed and what health attributes are exposed. It does not fully spell out the exact return shape or possible pagination, but the lack of parameters and the simple listing nature keep this gap minor.
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 zero parameters and the schema coverage is effectively complete, so there is nothing for the description to clarify. The baseline of 4 applies, and the description appropriately avoids inventing parameter-related guidance.
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 states a specific verb and resource: listing monitors. It also adds scope ('on your API key') and a meaningful detail about what is included (delivery health), which clearly distinguishes it from sibling list tools like list_sources and list_datasets.
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 provides clear context: this tool is for viewing monitors tied to the caller's API key, including their health status. It does not explicitly mention when not to use it or name alternatives, but the resource-specific wording makes the appropriate use case evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the official statistical sources served by this data layer (e.g. Statistics Canada, FRED), with dataset/series counts, cadence notes, and terms links. Start here to see what exists.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds useful behavioral content about what the response includes: dataset/series counts, cadence notes, and terms links. It does not contradict the annotations and gives enough context for a simple read-only listing.
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, front-loads the core purpose and output contents, and ends with clear starting guidance. Every sentence adds value with no repetition of already-structured annotation data.
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 zero-parameter, read-only listing tool with no output schema, the description provides sufficient context: what is listed, what the entries contain, and where this tool fits in the workflow. Nothing critical is missing for an agent to select and invoke it correctly.
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 zero parameters and the schema has no properties, so parameter semantics are trivially satisfied. The description appropriately avoids inventing parameter details that do not exist, matching the baseline for a zero-parameter tool.
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 uses a specific verb ('List') and resource ('official statistical sources served by this data layer'), with concrete examples (Statistics Canada, FRED) and output details (counts, cadence notes, terms links). It is clear, though it does not explicitly differentiate itself from the sibling list_datasets, so it stops short of a 5.
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 phrase 'Start here to see what exists' gives clear guidance that this is the initial discovery entry point among the sibling tools. It does not state when not to use it or explicitly name alternatives, so it lacks full exclusionary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find series across ALL sources in one call: case-insensitive search over series ids, indicator names, geographies, and dataset titles (e.g. "unemployment canada", "10-year treasury", "CPI"). Returns candidate series with units, coverage, verification status, and license, plus datasetMatches from the wider dataset index — datasets whose series can be requested by source-native id and are fetched from the official source on first call. The fastest path from a question to the exact series id to fetch or pin in the answer tool.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 20) | |
| query | Yes | Search terms, e.g. "unemployment rate canada" | |
| offset | No | Skip the first N ranked hits (default 0). When hasMore is true, call again with offset = offset + limit. | |
| source | No | Optional source slug to restrict to, e.g. 'fred' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses case-insensitive search behavior, the fields searched, the contents of the returned candidate series (units, coverage, verification status, license), and the special datasetMatches behavior including on-first-call fetching. This gives the agent a clear model of what will happen.
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 compact and front-loaded with the core capability, followed by a high-value explanation of the return behavior. Every sentence adds useful information, and there is no 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?
With no output schema, the description compensates by summarizing the return shape (candidate series fields and datasetMatches). It provides enough context for an agent to decide and invoke the tool, though it doesn't describe edge cases like empty result behavior or pagination beyond what the schema already covers.
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?
Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining that the query is case-insensitive and what fields it matches, plus concrete examples. It doesn't add much about limit/offset/source, but the schema already documents those adequately.
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 ('Find'), the resource ('series across ALL sources'), and the exact scope of the search (series ids, indicator names, geographies, dataset titles). It gives concrete examples and explains what is returned, which distinguishes it from siblings like list_sources or get_series.
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 conveys the intended use case clearly: it is the fast path from a question to the exact series id to fetch or pin, and it searches across all sources in one call. It does not explicitly name alternatives or state when not to use it, but the context is strong enough to guide tool selection.
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.
v0.2.2answercreate_monitordeep_analysisdelete_monitorget_observationsget_seriesget_series_statslist_datasetslist_monitorslist_sourcessearch_catalogScored across 11 tools
Each tool targets a distinct resource or action: source/dataset discovery, series search, metadata, observations, summary stats, monitor lifecycle, and two analysis tiers. The adjacent `answer` and `deep_analysis` are explicitly differentiated by latency and report depth, so an agent should not confuse them.
Most tools follow a clean verb_noun structure (`list_sources`, `get_series`, `create_monitor`, `delete_monitor`). The two flagship tools, `answer` and `deep_analysis`, deviate from that pattern, but the names remain self-descriptive and the mixed style is not chaotic.
Eleven tools is well within the ideal range for this service and each earns its place: discovery, retrieval, stats, monitors, and analysis are all covered without redundancy. The count feels neither thin nor bloated.
The surface covers the full workflow an agent needs: search and list data sources/datasets, fetch series metadata and observations, compute summary statistics, create/list/delete monitors, and run one-shot or deep analyses. There are no dead ends for the stated purpose of serving official statistics.
75 MCP tools: SEC financials, FRED economics, IRS 990, FDA, FX, UK Companies House.
Macroeconomic and other official data from 170+ publishers, resolved from natural language with provenance.
Fetch US Bureau of Labor Statistics data — CPI, unemployment, wages, JOLTS, and more via MCP.
Hosted MCP server for live public-data APIs and Skills for AI agents.
