Tool Contracts

Overview

A tool contract defines how an MCP tool is called and what it returns.

In Lightcast MCP, contracts are dataset-aware, meaning the valid inputs for a tool can change depending on the selected dataset. The same tool may support different dimensions, metrics, filters, and output structures across datasets.

Tool contracts allow agents to discover supported capabilities at runtime rather than relying on hardcoded request formats.

The safest way to work with tool contracts is to discover them at runtime with tool_info.

Contract Discovery

Use tool_info before calling an analysis tool to retrieve the contract for a specific dataset and tool pair.

{
  "dataset": "job_postings",
  "toolName": "count"
}

The response includes the complete JSON Schema for that combination, including supported dimensions, metrics, filters, operators, required properties, limits, and request structure.

Agents should use the returned schema to construct requests rather than assuming dimensions, metrics, or field names.

Agents should not guess schemas, dimension identifiers, or metric names. Use glossary, tool_info, and classify as discovery steps before running an analysis.

Available Tools

Lightcast MCP currently provides the following tools. Tools

Tool	Category	Purpose
`tool_info`	Advisory	Returns the exact JSON Schema for a dataset and analysis tool pair.
`classify`	Resolver	Resolves raw user text into canonical taxonomy IDs.
`count`	Analytics	Retrieves counts of records or entities.
`distribution`	Analytics	Returns distribution buckets or percentile-style spread for a supported metric.
`estimate`	Analytics	Calculates statistical aggregates or estimated values.
`list`	Analytics	Returns a granular sample of individual job postings.
`timeseries`	Analytics	Returns metric values over time buckets.
`top`	Analytics	Ranks entities within a dimension by a selected metric.
`glossary`	Advisory	Returns dataset discovery information.

Inputs

Analysis tools use a shared set of concepts, although availability varies by dataset and tool.

Input	Description
`dataset`	Dataset identifier, such as `job_postings` or `profiles`.
`filter`	Dataset/tool-specific dimension constraints.
`metrics`	Metrics to return for `count`, `estimate`, or `timeseries`.
`domainMetric`	Metric whose distribution is being measured by `distribution`.
`extraMetrics`	Additional metrics returned with distribution buckets, where supported.
`rankDimension`	Dimension and level used by `top` to group rankings.
`rankBy`	Metric used by `top` to order rankings.
`fields`	Job posting fields returned by `list`.
`limit`	Maximum number of records or ranked results, where supported.

Outputs

Tool responses are normalized by tool type.

Tool	Output shape
`tool_info`	JSON Schema for valid input.
`classify`	Candidate taxonomy results with ID, name, level, and optional confidence.
`count` and `estimate`	A `metrics` object mapping requested metric names to numeric or null values.
`distribution`	A domain and buckets, or year and percentile buckets for government occupations.
`list`	Job posting records and a total result count.
`timeseries`	Interval, totals, and metric values by time bucket.
`top`	Totals and ranked dimension values.
`glossary`	Markdown describing datasets and supported tools.

Validation

Tool contracts are enforced through JSON Schema validation and runtime validation.

Requests may be rejected for reasons such as:

Unsupported datasets
Unsupported dataset and tool combinations
Unsupported dimensions
Unsupported metrics
Invalid operators
Missing required filters
Invalid value structures

Structured error responses are returned when validation fails. For error-handling details, see Errors