MCP tool reference¶
37 tools, generated from the running server’s schemas. This page rebuilds with every documentation deployment.
All tools query external Lightcast services. They are read-only, but may consume your subscription quota. Premium API permissions are independent of basic taxonomy access.
Benchmarks¶
get_benchmark_metadata¶
Discover benchmark dimensions, available datasets, regions, and taxonomy versions.
| Parameter | Required | Default |
|---|---|---|
| No parameters | — | — |
get_occupation_benchmark¶
Benchmark a LOT occupation. metrics are dataset names (salary, demand, specializedSkills, etc.); region is {"nation": "us"}. Preserves warnings about unavailable datasets.
| Parameter | Required | Default |
|---|---|---|
occupation_id |
Yes | — |
metrics |
No | null |
region |
No | null |
dimension |
No | "lotocc" |
lot_version |
No | "7" |
Full input schema
{
"additionalProperties": false,
"properties": {
"occupation_id": {
"minLength": 1,
"type": "string"
},
"metrics": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"region": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"default": null
},
"dimension": {
"default": "lotocc",
"enum": [
"lotocc",
"lotspecocc"
],
"type": "string"
},
"lot_version": {
"default": "7",
"enum": [
"6",
"7"
],
"type": "string"
}
},
"required": [
"occupation_id"
],
"type": "object"
}
Classification¶
classify_occupation¶
Classify a title and optional description to LOT specialized occupations. May consume a limited classifier quota.
| Parameter | Required | Default |
|---|---|---|
title |
Yes | — |
description |
No | "" |
limit |
No | 5 |
confidence_threshold |
No | 0.5 |
version |
No | "latest" |
Full input schema
{
"additionalProperties": false,
"properties": {
"title": {
"minLength": 1,
"type": "string"
},
"description": {
"default": "",
"type": "string"
},
"limit": {
"default": 5,
"maximum": 5,
"minimum": 1,
"type": "integer"
},
"confidence_threshold": {
"default": 0.5,
"maximum": 1,
"minimum": 0,
"type": "number"
},
"version": {
"default": "latest",
"minLength": 1,
"type": "string"
}
},
"required": [
"title"
],
"type": "object"
}
get_classification_metadata¶
Get source types for an active classifier release. latest discovers the newest nonexpired release.
| Parameter | Required | Default |
|---|---|---|
version |
No | "latest" |
Full input schema
list_classification_releases¶
List classifier releases, removal dates, and supported taxonomy versions.
| Parameter | Required | Default |
|---|---|---|
| No parameters | — | — |
list_taxonomy_mappings¶
Discover mapping names and source/destination taxonomy versions; do this before mapping IDs.
| Parameter | Required | Default |
|---|---|---|
| No parameters | — | — |
map_taxonomy_concepts¶
Map concept IDs using a mapping name returned by list_taxonomy_mappings.
| Parameter | Required | Default |
|---|---|---|
mapping_name |
Yes | — |
ids |
Yes | — |
Full input schema
Core_Lmi¶
get_core_lmi_dimension¶
Find valid dimension codes by name/code search, or browse a hierarchy using level and aggregation_path. Search and hierarchy filters are separate modes. Use returned child codes exactly, including leading zeros; metadata pagination is local.
| Parameter | Required | Default |
|---|---|---|
dataset |
Yes | — |
dimension |
Yes | — |
version |
No | "latest" |
search |
No | null |
level |
No | null |
aggregation_path |
No | null |
limit |
No | 50 |
offset |
No | 0 |
Full input schema
{
"additionalProperties": false,
"properties": {
"dataset": {
"minLength": 1,
"type": "string"
},
"dimension": {
"minLength": 1,
"type": "string"
},
"version": {
"default": "latest",
"minLength": 1,
"type": "string"
},
"search": {
"anyOf": [
{
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"level": {
"anyOf": [
{
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"aggregation_path": {
"anyOf": [
{
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"limit": {
"default": 50,
"maximum": 500,
"minimum": 1,
"type": "integer"
},
"offset": {
"default": 0,
"minimum": 0,
"type": "integer"
}
},
"required": [
"dataset",
"dimension"
],
"type": "object"
}
get_core_lmi_metadata¶
Inspect a Core LMI release's attributes, dimensions and available metrics before querying. Filter metrics by substring (e.g. Jobs. or Earnings); follow metrics_pagination.next_offset. Release version is different from metric year.
| Parameter | Required | Default |
|---|---|---|
dataset |
Yes | — |
version |
No | "latest" |
metric_query |
No | "" |
limit |
No | 50 |
offset |
No | 0 |
Full input schema
{
"additionalProperties": false,
"properties": {
"dataset": {
"minLength": 1,
"type": "string"
},
"version": {
"default": "latest",
"minLength": 1,
"type": "string"
},
"metric_query": {
"default": "",
"type": "string"
},
"limit": {
"default": 50,
"maximum": 500,
"minimum": 1,
"type": "integer"
},
"offset": {
"default": 0,
"minimum": 0,
"type": "integer"
}
},
"required": [
"dataset"
],
"type": "object"
}
get_core_lmi_versions¶
List releases for an accessible Core LMI dataset. latest_numeric is discovered numerically, never taken from array order. Pin a returned release for reproducible queries; base/example require explicit selection.
| Parameter | Required | Default |
|---|---|---|
dataset |
Yes | — |
Full input schema
list_core_lmi_datasets¶
Discover Core LMI datasets and releases accessible to your account (agnitio scope). Optionally include descriptions and filter by name/text. Follow pagination.next_offset; metadata pagination is local after one upstream fetch.
| Parameter | Required | Default |
|---|---|---|
query |
No | "" |
include_definitions |
No | false |
limit |
No | 20 |
offset |
No | 0 |
Full input schema
{
"additionalProperties": false,
"properties": {
"query": {
"default": "",
"type": "string"
},
"include_definitions": {
"default": false,
"type": "boolean"
},
"limit": {
"default": 20,
"maximum": 500,
"minimum": 1,
"type": "integer"
},
"offset": {
"default": 0,
"minimum": 0,
"type": "integer"
}
},
"type": "object"
}
query_core_lmi¶
Query employment, wages, education or other Core LMI measures using discovered metrics and dimension codes. Read-only POST; consumes quota. Supports named aggregations, mapLevel, LocationQuotient, ShiftShare, sorting and bounded pagination (100 rows default, 500 maximum per page, first 5000 rows accessible). data is column-oriented: combine values at matching row indices. Preserve returned version and upstream metadata; missing/suppressed values are not zero. Use sortBy for repeatable pages. Offset is applied locally to a bounded prefix because the service ignores native offset. Follow pagination.next_offset; narrow the query if has_more is true at window_limit. totalRows is upstream metadata, not a grand total.
| Parameter | Required | Default |
|---|---|---|
dataset |
Yes | — |
query |
Yes | — |
version |
No | "latest" |
Full input schema
{
"additionalProperties": false,
"properties": {
"dataset": {
"minLength": 1,
"type": "string"
},
"query": {
"additionalProperties": false,
"properties": {
"metrics": {
"items": {
"additionalProperties": false,
"properties": {
"name": {
"description": "Exact metric from dataset metadata, e.g. Jobs.2025.",
"minLength": 1,
"type": "string"
},
"as": {
"anyOf": [
{
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"operation": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"name": {
"enum": [
"LocationQuotient",
"ShiftShare"
],
"type": "string"
},
"geoparent": {
"minLength": 1,
"type": "string"
},
"along": {
"minLength": 1,
"type": "string"
},
"base": {
"anyOf": [
{
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"name",
"geoparent",
"along"
],
"type": "object"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"name"
],
"type": "object"
},
"maxItems": 20,
"minItems": 1,
"type": "array"
},
"constraints": {
"items": {
"additionalProperties": false,
"properties": {
"dimensionName": {
"minLength": 1,
"type": "string"
},
"asIdentity": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null
},
"map": {
"anyOf": [
{
"additionalProperties": {
"items": {
"minLength": 1,
"type": "string"
},
"maxItems": 1000,
"minItems": 1,
"type": "array"
},
"maxProperties": 500,
"minProperties": 1,
"propertyNames": {
"minLength": 1
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Output labels mapped to dimension codes. Use codes returned by dimension discovery."
},
"mapLevel": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"level": {
"minimum": 0,
"type": "integer"
},
"predicate": {
"items": {
"type": "integer"
},
"maxItems": 1000,
"minItems": 1,
"type": "array"
}
},
"required": [
"level",
"predicate"
],
"type": "object"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"dimensionName"
],
"type": "object"
},
"maxItems": 20,
"type": "array"
},
"sortBy": {
"anyOf": [
{
"items": {
"additionalProperties": false,
"properties": {
"name": {
"minLength": 1,
"type": "string"
},
"direction": {
"default": "ascending",
"enum": [
"ascending",
"descending"
],
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
},
"maxItems": 20,
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"offset": {
"default": 0,
"minimum": 0,
"type": "integer"
},
"limit": {
"default": 100,
"maximum": 500,
"minimum": 1,
"type": "integer"
}
},
"required": [
"metrics",
"constraints"
],
"type": "object"
},
"version": {
"default": "latest",
"minLength": 1,
"type": "string"
}
},
"required": [
"dataset",
"query"
],
"type": "object"
}
Pathways¶
get_career_next_steps¶
Find potential next occupations from the Career Pathways model. Discover available categories in metadata.
| Parameter | Required | Default |
|---|---|---|
occupation_id |
Yes | — |
dimension |
No | "lotspecocc" |
limit |
No | 10 |
nation |
No | "us" |
categories |
No | null |
lot_version |
No | "7" |
Full input schema
{
"additionalProperties": false,
"properties": {
"occupation_id": {
"minLength": 1,
"type": "string"
},
"dimension": {
"default": "lotspecocc",
"enum": [
"soc",
"onet",
"lotocc",
"lotspecocc"
],
"type": "string"
},
"limit": {
"default": 10,
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"nation": {
"default": "us",
"minLength": 1,
"type": "string"
},
"categories": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"lot_version": {
"default": "7",
"enum": [
"6",
"7"
],
"type": "string"
}
},
"required": [
"occupation_id"
],
"type": "object"
}
get_career_skill_gap¶
Compare source and destination occupations within the same taxonomy to identify skill gaps.
| Parameter | Required | Default |
|---|---|---|
source_id |
Yes | — |
destination_id |
Yes | — |
dimension |
No | "lotspecocc" |
limit |
No | 20 |
nation |
No | "us" |
lot_version |
No | "7" |
Full input schema
{
"additionalProperties": false,
"properties": {
"source_id": {
"minLength": 1,
"type": "string"
},
"destination_id": {
"minLength": 1,
"type": "string"
},
"dimension": {
"default": "lotspecocc",
"enum": [
"soc",
"onet",
"lotocc",
"lotspecocc"
],
"type": "string"
},
"limit": {
"default": 20,
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"nation": {
"default": "us",
"minLength": 1,
"type": "string"
},
"lot_version": {
"default": "7",
"enum": [
"6",
"7"
],
"type": "string"
}
},
"required": [
"source_id",
"destination_id"
],
"type": "object"
}
get_pathways_metadata¶
Discover career-pathway dimensions, categories, nations, and taxonomy versions.
| Parameter | Required | Default |
|---|---|---|
| No parameters | — | — |
Postings¶
get_job_posting_details¶
Retrieve a US posting by ID. Requires posting-detail permissions.
| Parameter | Required | Default |
|---|---|---|
posting_id |
Yes | — |
Full input schema
get_posting_rankings¶
Rank a facet such as skills_name or company_name by unique US postings. filters.when is required.
| Parameter | Required | Default |
|---|---|---|
facet |
Yes | — |
filters |
Yes | — |
limit |
No | 10 |
Full input schema
{
"additionalProperties": false,
"properties": {
"facet": {
"minLength": 1,
"type": "string"
},
"filters": {
"additionalProperties": true,
"description": "A required timeframe plus native JPA filter fields discovered in metadata.",
"properties": {
"when": {
"anyOf": [
{
"const": "active",
"type": "string"
},
{
"additionalProperties": false,
"properties": {
"start": {
"pattern": "^[0-9]{4}-[0-9]{2}(-[0-9]{2})?$",
"type": "string"
},
"end": {
"pattern": "^[0-9]{4}-[0-9]{2}(-[0-9]{2})?$",
"type": "string"
},
"type": {
"default": "active",
"enum": [
"posted",
"active",
"expired"
],
"type": "string"
}
},
"required": [
"start",
"end"
],
"type": "object"
}
]
}
},
"required": [
"when"
],
"type": "object"
},
"limit": {
"default": 10,
"maximum": 100,
"minimum": 1,
"type": "integer"
}
},
"required": [
"facet",
"filters"
],
"type": "object"
}
get_posting_statistics¶
Get US posting totals; metrics default to unique_postings. filters.when is required. Discover filters and metrics in metadata.
| Parameter | Required | Default |
|---|---|---|
filters |
Yes | — |
metrics |
No | null |
Full input schema
{
"additionalProperties": false,
"properties": {
"filters": {
"additionalProperties": true,
"description": "A required timeframe plus native JPA filter fields discovered in metadata.",
"properties": {
"when": {
"anyOf": [
{
"const": "active",
"type": "string"
},
{
"additionalProperties": false,
"properties": {
"start": {
"pattern": "^[0-9]{4}-[0-9]{2}(-[0-9]{2})?$",
"type": "string"
},
"end": {
"pattern": "^[0-9]{4}-[0-9]{2}(-[0-9]{2})?$",
"type": "string"
},
"type": {
"default": "active",
"enum": [
"posted",
"active",
"expired"
],
"type": "string"
}
},
"required": [
"start",
"end"
],
"type": "object"
}
]
}
},
"required": [
"when"
],
"type": "object"
},
"metrics": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"filters"
],
"type": "object"
}
get_postings_metadata¶
Discover accessible US posting fields, filters, metrics, and available months.
| Parameter | Required | Default |
|---|---|---|
| No parameters | — | — |
search_job_postings¶
Search US postings with native filters including required when (active or a start/end range), e.g. {"when": "active", "title": ["ET6850661D6AE5FA86"], "city_name": ["Seattle, WA"]}. Use metadata to discover filters; requires postings:us.
| Parameter | Required | Default |
|---|---|---|
filters |
Yes | — |
limit |
No | 10 |
page |
No | 1 |
fields |
No | null |
Full input schema
{
"additionalProperties": false,
"properties": {
"filters": {
"additionalProperties": true,
"description": "A required timeframe plus native JPA filter fields discovered in metadata.",
"properties": {
"when": {
"anyOf": [
{
"const": "active",
"type": "string"
},
{
"additionalProperties": false,
"properties": {
"start": {
"pattern": "^[0-9]{4}-[0-9]{2}(-[0-9]{2})?$",
"type": "string"
},
"end": {
"pattern": "^[0-9]{4}-[0-9]{2}(-[0-9]{2})?$",
"type": "string"
},
"type": {
"default": "active",
"enum": [
"posted",
"active",
"expired"
],
"type": "string"
}
},
"required": [
"start",
"end"
],
"type": "object"
}
]
}
},
"required": [
"when"
],
"type": "object"
},
"limit": {
"default": 10,
"maximum": 10,
"minimum": 1,
"type": "integer"
},
"page": {
"default": 1,
"minimum": 1,
"type": "integer"
},
"fields": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"filters"
],
"type": "object"
}
Similarity¶
find_similar_skills¶
Find scored similar skills. Requires the separate Similarity API subscription.
| Parameter | Required | Default |
|---|---|---|
skill_id |
Yes | — |
limit |
No | 10 |
Full input schema
get_similarity_metadata¶
Discover Similarity models and the taxonomy versions they accept.
| Parameter | Required | Default |
|---|---|---|
| No parameters | — | — |
query_similarity¶
Query a Similarity model, e.g. soc, skill, lotspecocc-skill, or skill-lotocc. Only skill-input models accept a list. Preserves upstream warnings.
| Parameter | Required | Default |
|---|---|---|
model |
Yes | — |
input |
Yes | — |
limit |
No | 10 |
min_score |
No | 0.5 |
filter_ids |
No | null |
lot_version |
No | "7" |
Full input schema
{
"additionalProperties": false,
"properties": {
"model": {
"minLength": 1,
"type": "string"
},
"input": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"type": "string"
},
"type": "array"
}
]
},
"limit": {
"default": 10,
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"min_score": {
"default": 0.5,
"maximum": 1,
"minimum": 0,
"type": "number"
},
"filter_ids": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"lot_version": {
"default": "7",
"enum": [
"6",
"7"
],
"type": "string"
}
},
"required": [
"model",
"input"
],
"type": "object"
}
Skills¶
bulk_retrieve_skills¶
Retrieve multiple skills in one request.
| Parameter | Required | Default |
|---|---|---|
skill_ids |
Yes | — |
version |
No | "latest" |
Full input schema
extract_skills_from_text¶
Extract explicitly mentioned skills from text. Requires extraction permission and may consume a limited quota.
| Parameter | Required | Default |
|---|---|---|
text |
Yes | — |
confidence_threshold |
No | 0.5 |
version |
No | "latest" |
Full input schema
get_related_skills¶
Find related skills using the Skills API. Results are related skills, not scored Similarity mappings.
| Parameter | Required | Default |
|---|---|---|
skill_id |
Yes | — |
limit |
No | 10 |
version |
No | "latest" |
Full input schema
get_skill_details¶
Get a skill by its Lightcast ID.
| Parameter | Required | Default |
|---|---|---|
skill_id |
Yes | — |
version |
No | "latest" |
Full input schema
get_skills_metadata¶
Discover the Skills taxonomy version, supported fields, and skill types.
| Parameter | Required | Default |
|---|---|---|
version |
No | "latest" |
Full input schema
search_skills¶
Search the Skills taxonomy. skill_type accepts type IDs: ST1 (specialized), ST2 (common), ST3 (certification), comma-separated.
| Parameter | Required | Default |
|---|---|---|
query |
Yes | — |
limit |
No | 10 |
skill_type |
No | null |
version |
No | "latest" |
Full input schema
{
"additionalProperties": false,
"properties": {
"query": {
"minLength": 1,
"type": "string"
},
"limit": {
"default": 10,
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"skill_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"version": {
"default": "latest",
"minLength": 1,
"type": "string"
}
},
"required": [
"query"
],
"type": "object"
}
Titles¶
bulk_retrieve_titles¶
Retrieve multiple titles in one request.
| Parameter | Required | Default |
|---|---|---|
title_ids |
Yes | — |
version |
No | "latest" |
Full input schema
get_job_title_details¶
Retrieve a standardized title by its Lightcast ID.
| Parameter | Required | Default |
|---|---|---|
title_id |
Yes | — |
version |
No | "latest" |
Full input schema
get_titles_metadata¶
Discover the current Titles taxonomy version and available fields.
| Parameter | Required | Default |
|---|---|---|
version |
No | "latest" |
Full input schema
normalize_job_title¶
Normalize a raw job title, with confidence. Requires normalization permission; may consume a limited quota.
| Parameter | Required | Default |
|---|---|---|
title |
Yes | — |
version |
No | "latest" |
Full input schema
search_job_titles¶
Search standardized job titles. version is a Titles taxonomy version or latest.
| Parameter | Required | Default |
|---|---|---|
query |
Yes | — |
limit |
No | 10 |
version |
No | "latest" |
Full input schema
Workflows¶
analyze_job_posting_skills¶
Normalize a title and extract skills explicitly present in its title/description. Does not infer occupation skills. version controls Titles; skills_version controls Skills.
| Parameter | Required | Default |
|---|---|---|
job_title |
Yes | — |
job_description |
Yes | — |
extract_from_description |
No | true |
confidence_threshold |
No | 0.5 |
version |
No | "latest" |
skills_version |
No | "latest" |
Full input schema
{
"additionalProperties": false,
"properties": {
"job_title": {
"minLength": 1,
"type": "string"
},
"job_description": {
"type": "string"
},
"extract_from_description": {
"default": true,
"type": "boolean"
},
"confidence_threshold": {
"default": 0.5,
"maximum": 1,
"minimum": 0,
"type": "number"
},
"version": {
"default": "latest",
"minLength": 1,
"type": "string"
},
"skills_version": {
"default": "latest",
"minLength": 1,
"type": "string"
}
},
"required": [
"job_title",
"job_description"
],
"type": "object"
}
normalize_title_and_extract_skills¶
Normalize a title and extract explicitly mentioned skills using the current Classification release. May consume two classifier quota requests.
| Parameter | Required | Default |
|---|---|---|
title |
Yes | — |
confidence_threshold |
No | 0.6 |
version |
No | "latest" |
Full input schema
{
"additionalProperties": false,
"properties": {
"title": {
"minLength": 1,
"type": "string"
},
"confidence_threshold": {
"default": 0.6,
"maximum": 1,
"minimum": 0,
"type": "number"
},
"version": {
"default": "latest",
"minLength": 1,
"type": "string"
}
},
"required": [
"title"
],
"type": "object"
}
normalize_title_and_get_skills¶
Normalize a title, classify to LOT specialized occupations, then retrieve associated skills from Similarity. Requires three API permissions. Reports partial failures; version controls Titles only, classification_version controls classifiers, and lot_version must match the classifier's LOT major version.
| Parameter | Required | Default |
|---|---|---|
raw_title |
Yes | — |
max_occupations |
No | 5 |
max_skills_per_occupation |
No | 20 |
skill_type |
No | null |
confidence_threshold |
No | 0.5 |
version |
No | "latest" |
classification_version |
No | "latest" |
lot_version |
No | "7" |
Full input schema
{
"additionalProperties": false,
"properties": {
"raw_title": {
"minLength": 1,
"type": "string"
},
"max_occupations": {
"default": 5,
"maximum": 5,
"minimum": 1,
"type": "integer"
},
"max_skills_per_occupation": {
"default": 20,
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"skill_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"confidence_threshold": {
"default": 0.5,
"maximum": 1,
"minimum": 0,
"type": "number"
},
"version": {
"default": "latest",
"minLength": 1,
"type": "string"
},
"classification_version": {
"default": "latest",
"minLength": 1,
"type": "string"
},
"lot_version": {
"default": "7",
"enum": [
"6",
"7"
],
"type": "string"
}
},
"required": [
"raw_title"
],
"type": "object"
}