Tools

Lightcast MCP tools are MCP-callable capabilities that help agents discover labor market datasets, validate request schemas, resolve taxonomy values, and retrieve analytical results.

Tools are intentionally narrower than direct API access. They expose customer-facing tasks such as dataset discovery, classification, counts, estimates, distributions, record samples, time series, and rankings.

Note

This section documents only tools validated in the tool inventory. Placeholder scaffold pages for unsupported capabilities are not included in the tools navigation.

Tool Philosophy

Lightcast MCP is designed for intent-based tool use. An agent starts with a user question, identifies the dataset and tool that match the analytical intent, retrieves the exact input schema, resolves taxonomy values when needed, and then calls the analysis tool.

Step	Tooling role
Understand available data	Use `glossary` to discover datasets and supported tools.
Validate the contract	Use `tool_info` to retrieve the exact schema for a dataset and analysis tool.
Normalize user language	Use `classify` to resolve raw terms into canonical taxonomy IDs.
Analyze data	Use `count`, `distribution`, `estimate`, `list`, `timeseries`, or `top`.

For the broader conceptual model, see Tool Contracts.

Tools Versus APIs

Direct APIs expose broad service-specific request models. Lightcast MCP tools expose a smaller, dataset-aware interface optimized for agent workflows.

Direct API thinking	Lightcast MCP tool thinking
"Which endpoint should I call?"	"Which tool matches the analytical intent?"
"Which backend parameters are required?"	"What does `tool_info` say the current contract requires?"
"How do I normalize this occupation or skill?"	"Which `classify` result should be used as the canonical ID?"
"How do I map the response?"	"Which normalized MCP output shape does this tool return?"

Tool Catalog

Tool	Category	Purpose
Tool Info	Metadata/schema discovery	Return the exact JSON Schema for a dataset and analysis tool pair.
Classify	Taxonomy lookup/canonicalization	Resolve raw user text into canonical taxonomy IDs.
Count	Aggregation/count	Retrieve counts of records or entities for a dataset.
Distribution	Distribution/statistical spread	Return percentile-style distributions for a supported metric.
Estimate	Aggregation/estimate	Calculate statistical aggregates or estimated values for supported metrics.
List	Record listing/sample	Return a granular sample of individual job postings.
Timeseries	Time series/trend	Return metric values over time buckets.
Top	Ranking/top-N	Rank entities within a dimension by a selected metric.
Glossary	Metadata/discovery	Return dataset discovery information for tool and dataset selection.

Relationship To Datasets

Tools operate on validated datasets. Not every tool supports every dataset.

Tool	Job Posting	Profile	Core LMI
`glossary`	Describes	Describes	Describes
`tool_info`	Yes	Yes	Yes
`classify`	Dimension-dependent	Dimension-dependent	Dimension-dependent
`count`	Yes	Yes	No
`distribution`	Yes	Yes	Yes
`estimate`	Yes	Yes	Yes
`list`	Yes	No	No
`timeseries`	Yes	No	No
`top`	Yes	Yes	No

See Job Posting Dataset and Profile Dataset.

Relationship To Dimensions And Metrics

Tools use dimensions and metrics differently:

Concept	How tools use it
Dimensions	Filters and ranking dimensions narrow or group the data.
Metrics	Count, estimate, distribution, timeseries, and top tools return or rank by supported metrics.
Taxonomies	Classifiable dimensions require canonical IDs before analysis.
Filters	Analysis tools use filters to scope the dataset.

Recommended Workflow

Use Glossary to choose a dataset.
Use Tool Info to retrieve the schema for the selected analysis tool.
Use Classify for classifiable dimension values.
Use the analysis tool that matches the question.
Handle structured errors according to Errors.