MCP reference

Data Gatherers MCP tools

This public reference is generated from the backend MCP LLM catalog. It documents the safe client-facing tools, scopes, workflows, and caveats that LLM clients should follow when working with Data Gatherers.

Authentication

• Authorization server: https://oidc.datagatherers.com
• MCP resource: https://mcp.datagatherers.com/mcp
• Protected resource metadata: https://mcp.datagatherers.com/.well-known/oauth-protected-resource

Scopes

Workflows

Explore accessible projects

Discover which Data Gatherers projects the authenticated user can access before asking project-specific questions.

1. Call datagatherers_list_projects with a small limit.
2. Select one project ID from the returned project list.
3. Call datagatherers_get_project_context for safe coverage and next-tool hints.

Run an aggregate project analysis

Choose a supported aggregate analysis and run it with bounded, authorized filters.

1. Call datagatherers_list_projects if no project ID is known.
2. Call datagatherers_get_project_context to understand country/provider coverage.
3. Call datagatherers_describe_project_analysis to inspect supported analyses, filter rules, and scoped values.
4. Call datagatherers_query_project_analysis with the narrowest useful filter and a small result limit.
5. Explain caveats, truncation, and freshness evidence in the final answer.

Compare countries, providers, or projects

Compare authorized markets using the same aggregate analysis across multiple targets.

1. Call datagatherers_describe_project_analysis for each unfamiliar project.
2. Choose a comparable analysis and compatible filters.
3. Call datagatherers_compare_markets with two to six targets.
4. Use returned coverage and freshness caveats before drawing conclusions.

Investigate missing or stale coverage

Explain why an analysis may be empty, partial, or not comparable.

1. Call datagatherers_explain_analysis_coverage with the project and relevant filters.
2. Review country/provider counts, freshness evidence, and caveats.
3. Only then decide whether an aggregate query or comparison is meaningful.

Tool reference

datagatherers_list_projects

List Data Gatherers projects visible to the authenticated user.

client-facing read-only

Required scopes

• mcp:datagatherers:read

Use when

• The user asks what projects, markets, or datasets are available.
• A later tool requires a projectId and none is known.

Input

• limit: optional integer from 1 to 50; defaults to 25.
• offset: optional non-negative integer for pagination.
• search: optional case-insensitive project-name search string.

Output

• Projects include id, name, and type only.
• totalCount reports the full authorized match count.

Caveats

• The result is filtered by the authenticated user's existing project permissions.
• Hidden projects are excluded.

datagatherers_get_project_context

Describe safe metadata and aggregate coverage for one authorized Data Gatherers project.

client-facing read-only

Required scopes

• mcp:datagatherers:read

Use when

• The user asks what a project contains or whether a market/provider is covered.
• You need scoped country/provider values before querying analysis.

Input

• projectId: required 24-character Data Gatherers project ID.
• includeCities: optional boolean to include a top-city aggregate sample.
• cityLimit: optional integer from 1 to 25.
• providerLimit: optional integer from 1 to 100.
• iso/provider: optional scoped filters for coverage context.

Output

• Project summary, authorized country/provider coverage counts, optional top cities, and supported next tools.
• capabilities.rawDataAccess is always false.

Caveats

• Coverage metadata is not a guarantee that every analysis has fresh data for every segment.
• Use coverage explanation for freshness-sensitive conclusions.

datagatherers_describe_project_analysis

Describe registered aggregate analyses, registered filter option providers, and safe filter rules for one authorized project.

client-facing read-only

Required scopes

• mcp:datagatherers:analysis:read

Use when

• Before calling datagatherers_query_project_analysis for an unfamiliar project or analysis.
• The user asks which analyses or filters are supported.

Input

• projectId: required 24-character Data Gatherers project ID.
• includeScopedValues: optional boolean; defaults to true.
• providerLimit: optional integer from 1 to 100 for scoped provider examples.

Output

• Supported analysis names, filter contract, allowed operators, budgets, scoped values, examples, and rawDataAccess=false.

Caveats

• This is metadata-only and does not execute filter option queries or analysis calculations.
• Use returned scoped values to avoid unauthorized filters.

datagatherers_query_project_analysis

Run any registered aggregate Data Gatherers project analysis with safe bounded filters. Returns aggregate results only, never raw scraped records.

client-facing read-only

Required scopes

• mcp:datagatherers:analysis:read

Use when

• The user asks for numeric aggregate analysis after a project and supported analysis have been identified.
• You need bounded aggregate series for one authorized project.

Input

• projectId: required 24-character Data Gatherers project ID.
• analysis: required supported aggregate analysis name from datagatherers_describe_project_analysis.
• filter: optional bounded JSON object using platform filter fields and safe operators.
• limit: optional integer from 1 to 25 for returned aggregate series.

Output

• ok flag, project summary, applied filters, result summary, optional aggregate result, supported analyses, and rawDataAccess=false.

Caveats

• Never use this to request raw listings or source records.
• Use the narrowest authorized filter that answers the question.
• If result.ok is false, report the error code and suggestion rather than inventing data.

datagatherers_explain_analysis_coverage

Explain safe coverage, freshness evidence, caveats, and recommended next steps for an authorized project/filter set. Returns metadata only, never raw scraped records.

client-facing read-only

Required scopes

• mcp:datagatherers:analysis:read

Use when

• An aggregate query is empty, stale, unexpectedly partial, or hard to compare.
• The user asks whether data coverage is sufficient for a conclusion.

Input

• projectId: required 24-character Data Gatherers project ID.
• analysis: optional aggregate analysis name.
• filter: optional bounded project-scoped filter.
• includeCities/cityLimit/providerLimit: optional coverage sample controls.

Output

• Coverage counts, freshness evidence, caveats, next steps, resource links, and rawDataAccess=false.

Caveats

• Base snapshot freshness may not prove freshness for every integration-specific or Ampere-backed analysis.
• Use caveats in the final answer when making market claims.

datagatherers_compare_markets

Compare authorized Data Gatherers markets across countries, providers, or projects using bounded aggregate analysis queries. Returns aggregate results only, never raw scraped records.

client-facing read-only

Required scopes

• mcp:datagatherers:analysis:read

Use when

• The user asks to compare countries, providers, or projects using one aggregate metric set.
• You have already confirmed that the targets are comparable and authorized.

Input

• analysis: required supported aggregate analysis name.
• targets: required array of 2 to 6 authorized project/filter targets.
• sharedFilter: optional filter merged into every target.
• limit: optional integer from 1 to 25 per target.
• providerLimit: optional integer from 1 to 100 for coverage inspection.

Output

• Per-target project, filters, freshness, coverage, aggregate result or error, comparison caveats, and rawDataAccess=false.

Caveats

• Do not compare targets with incompatible filters, freshness evidence, or analysis semantics without saying so.
• Report failed targets separately instead of hiding them.