# Data Gatherers LLM Tool Guide

Catalog version: 2026-05-10
Schema version: 1.0.0
MCP protocol version: 2025-06-18

## Purpose

Authenticated, read-only aggregate marketplace intelligence tools for authorized Data Gatherers users.

Public LLM documentation describes safe tool usage only. Actual MCP calls require user authentication and existing Data Gatherers permissions.

## Safety and data boundaries

- Never request or expect raw scraped records from client-facing MCP tools.
- Client-facing MCP tools expose metadata, coverage, freshness evidence, and aggregate analysis only.
- Every tool call is authorized against the authenticated user's organizations, projects, roles, and scopes.
- Use project-scoped country, provider, and integration values returned by the tools before constructing filters.
- Treat empty aggregate responses as inconclusive until coverage and freshness have been checked.

### aggregate-only

Client-facing tools return aggregate statistics, metadata, coverage, and caveats; they do not expose individual scraped listings or raw source records.

### user-permission-bound

Tool visibility and execution follow the authenticated user's existing Data Gatherers project permissions.

### bounded-output

List and analysis tools cap returned projects, providers, cities, comparison targets, and aggregate series to reduce accidental over-querying.

## Authentication

OAuth 2.1 / OIDC through the Data Gatherers authorization server

- 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

- MCP clients should discover the protected resource metadata before starting OAuth.
- Access tokens must be audience-bound to the MCP resource URL.
- Dynamic MCP clients use Authorization Code with PKCE and are constrained to approved redirect URI patterns.

## Scopes

- mcp:access: Base scope required for MCP access.
- mcp:datagatherers:read: Read safe project metadata and coverage context.
- mcp:datagatherers:analysis:read: Read aggregate analysis catalogs, coverage explanations, analysis queries, and market comparisons.
- mcp:profile:read: Read the authenticated user's narrow account profile.

## Recommended workflows

### Explore accessible projects

Purpose: 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

Purpose: 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

Purpose: 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

Purpose: 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.

- Title: List authorized projects
- Classification: client-facing
- Mutability: 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.

Call before:
- None

Good next calls:
- datagatherers_get_project_context
- datagatherers_describe_project_analysis

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

Example arguments:

{
  "search": "animals",
  "limit": 5
}


### datagatherers_get_project_context

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

- Title: Get safe project context
- Classification: client-facing
- Mutability: 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.

Call before:
- datagatherers_list_projects

Good next calls:
- datagatherers_describe_project_analysis
- datagatherers_explain_analysis_coverage

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

Example arguments:

{
  "projectId": "000000000000000000000000",
  "includeCities": true,
  "cityLimit": 5
}


### datagatherers_describe_project_analysis

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

- Title: Describe available aggregate analyses
- Classification: client-facing
- Mutability: 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.

Call before:
- datagatherers_get_project_context

Good next calls:
- datagatherers_query_project_analysis
- datagatherers_compare_markets

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

Example arguments:

{
  "projectId": "000000000000000000000000",
  "includeScopedValues": true,
  "providerLimit": 20
}


### datagatherers_query_project_analysis

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

- Title: Query aggregate project analysis
- Classification: client-facing
- Mutability: 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.

Call before:
- datagatherers_describe_project_analysis

Good next calls:
- datagatherers_explain_analysis_coverage

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.

Example arguments:

{
  "projectId": "000000000000000000000000",
  "analysis": "stats",
  "filter": {
    "iso": "GB"
  },
  "limit": 10
}


### 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.

- Title: Explain analysis coverage
- Classification: client-facing
- Mutability: 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.

Call before:
- datagatherers_get_project_context

Good next calls:
- datagatherers_query_project_analysis
- datagatherers_compare_markets

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.

Example arguments:

{
  "projectId": "000000000000000000000000",
  "analysis": "stats",
  "filter": {
    "iso": "GB"
  },
  "includeCities": true
}


### 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.

- Title: Compare authorized markets
- Classification: client-facing
- Mutability: 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.

Call before:
- datagatherers_describe_project_analysis
- datagatherers_explain_analysis_coverage

Good next calls:
- None

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

Example arguments:

{
  "analysis": "stats",
  "targets": [
    {
      "label": "United Kingdom",
      "projectId": "000000000000000000000000",
      "filter": {
        "iso": "GB"
      }
    },
    {
      "label": "United States",
      "projectId": "000000000000000000000000",
      "filter": {
        "iso": "US"
      }
    }
  ],
  "limit": 10
}


## Resource templates

### datagatherers-project-summary

- URI template: datagatherers://projects/{projectId}/summary
- Required scopes: mcp:datagatherers:read

Safe project summary, capabilities, and compact coverage counts for an authorized project.

### datagatherers-project-analysis-catalog

- URI template: datagatherers://projects/{projectId}/analysis-catalog
- Required scopes: mcp:datagatherers:analysis:read

Available aggregate analyses, filter contract, scoped values, and examples for an authorized project.

### datagatherers-project-coverage

- URI template: datagatherers://projects/{projectId}/coverage
- Required scopes: mcp:datagatherers:analysis:read

Coverage, freshness, caveats, and recommended next steps for an authorized project.

## Prompt templates

### datagatherers_project_brief

- Required scopes: mcp:datagatherers:read, mcp:datagatherers:analysis:read

Summarize one authorized project with coverage, available analyses, caveats, and recommended next queries.

### datagatherers_market_analysis

- Required scopes: mcp:datagatherers:read, mcp:datagatherers:analysis:read

Guide an aggregate market analysis using authorized project context, analysis catalog, and safe filters.

### datagatherers_compare_countries

- Required scopes: mcp:datagatherers:read, mcp:datagatherers:analysis:read

Compare authorized countries/providers for a selected project and aggregate metric set.

### datagatherers_investigate_coverage_gap

- Required scopes: mcp:datagatherers:read, mcp:datagatherers:analysis:read

Investigate missing or stale coverage for an authorized project/filter set before running analysis queries.

## Error handling guidance

- If a tool returns an error object, report its code, message, and suggestion.
- If an aggregate result is empty, do not infer that the market has no activity until coverage and freshness have been checked.
- If a requested filter is rejected, use project context or the analysis catalog to discover authorized scoped values.
- If access is denied, explain that permissions follow the authenticated Data Gatherers account and organization/project access.