Core Concepts

Overview

Lightcast MCP organizes labor market intelligence into a small set of reusable concepts. Together, these concepts form the foundation of every tool contract and analytical workflow.

Understanding how these concepts relate to one another helps agents consistently translate user questions into valid analytical requests, regardless of which dataset or tool is being used.

How the Concepts Work Together

A typical Lightcast MCP request starts with a dataset and a tool. The tool contract for that combination defines which dimensions, metrics, filters, and outputs are valid.

The remaining concepts work within the boundaries established by the selected dataset and tool contract:

Dimensions describe how data can be filtered, grouped, or ranked.
Metrics define what is being measured.
Taxonomies convert user language into canonical identifiers.
Filters narrow the scope of analysis.

Example Workflow

Question: Which companies are hiring software developers in Seattle?

To answer this question, an agent would:

Select the job_postings dataset. The question is about hiring demand, which is a labor demand signal.
Select a ranking tool such as top.
Use dimensions such as occupation_soc or occupation_lot, location_us_city, and company.
Call classify to resolve "software developers" and "Seattle" into canonical taxonomy identifiers.
Specify a supported metric such as postings.unique_postings to define what the ranking is based on.

👉 Before constructing any analysis request, call tool_info for the selected dataset and tool pair. It returns the exact combinations, including which dimensions, metrics, and filters are valid. This is the safest way to avoid invalid tool calls.

Concept Map

Concept	Description
Dataset	The logical data domain a tool operates on, such as job postings, profiles, or government occupations.
Tool	An MCP-callable function with a defined input and output contract. The valid inputs for a tool depend on the dataset it's called with.
Dimension	An analytical attribute used to filter, group, or rank data within a tool request.
Metric	A measurable value a tool calculates or returns, such as unique postings, median salary, or jobs.
Taxonomy	A controlled vocabulary used to normalize user language into canonical identifiers.
Filter	A structured constraint that narrows the data included in a tool request.

Dataset

A dataset defines the labor market domain a tool operates on. Choosing the right dataset is the first decision in every agent workflow because it determines which tools, dimensions, and metrics are available.

Lightcast MCP currently implements three datasets:

job_postings
profiles
core_lmi

If you're unsure which dataset fits the user's question, call glossary first. It describes each dataset and lists its supported tools.

Tool

A tool is an MCP-callable function with a defined input and output contract. The valid inputs, including which dimensions, metrics, and filters are accepted, depend on the dataset the tool is called with.

Lightcast MCP tools fall into two categories:

Category	Tools	Purpose
Metadata Tools	`glossary`, `tool_info`, `classify`	Discover available datasets and tools, retrieve dataset-specific JSON Schemas, and resolve user text to canonical taxonomy identifiers.
Analysis Tools	`count`, `distribution`, `estimate`, `list`, `timeseries`, `top`	Retrieve analytical results from a supported dataset.

Always use metadata tools before calling an analysis tool. They exist to make the analysis tool call correct the first time.

Dimension

A dimension is an analytical attribute used to narrow or organize a tool result. Depending on the tool and dataset, dimensions can describe occupations, skills, locations, companies, industries, education levels, time periods, salary ranges, and more.

Dimensions fall into two categories that affect how you supply their values:

Taxonomy-backed dimensions require canonical IDs resolved through the classify tool. Passing raw user text for these dimensions will result in a validation error.
Structured dimensions accept well-defined value types such as ranges, enumerations, or boolean flags. These don't require taxonomy resolution.

To confirm which category a dimension belongs to and what value format it expects, check the results returned by tool_info.

Metric

A metric is a value a tool calculates or returns as part of its output. Metrics are dataset-specific. The same concept may have different metric names across datasets.

For example:

postings.unique_postings belongs to job_postings
profiles.unique_profiles belongs to profiles

Taxonomy

A taxonomy is a controlled vocabulary that assigns stable, canonical identifiers to concepts such as skills, occupations, industries, locations, benefits, companies, schools, and education programs.

Many dimensions require canonical identifiers rather than free-form text. For example, passing software developer where an occupation identifier is required will fail validation.

Using taxonomy identifiers correctly helps prevent one of the most common validation errors: providing raw user text where a structured identifier is expected.

Filter

A filter limits the data included in a tool request. Filters are built from dimensions supported by the selected dataset and tool. Not every dimension can be used as a filter for every tool.

For example, job_postings analysis tools require a time filter. Omitting it results in a validation error rather than a partial result set.

Other dimensions, such as skill or location_us_area, may be used as optional filters when supported by the selected tool contract.

To determine which filters are required and which are optional, review the schema returned by tool_info.