Skip to main content
Glama

Find a job title's SOC codes

lookup_soc
Read-onlyIdempotent

The SOC codes employers filed a job title under in DOL's PERM, prevailing wage and LCA files, with each code's share of the title's filings. For a code: its title, O*NET's description and core tasks, the titles employers filed most under it, and its PERM approval rate and median offered wage (under the site's floors). For a 2010 code: the 2018 codes it became. No key, under the same shared limits as the employer lookup. Example: {"q":"data scientist"}.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "q": "<q>"
    },
    "name": "lookup_soc"
  }
}

Input Schema

NameRequiredDescriptionDefault
qYesA job title or a SOC code (15-1252, 15-1252.00 or 151252), 2 to 80 characters. Example: data scientist.

Output Schema

NameRequiredDescriptionDefault
asOfYesThe date the data is true for, YYYY-MM-DD, when one applies.
dataYesThe answer, or found: false when no record matched.
pageYesThe page on permtracker.app that shows the same thing. Cite it.
sourceYesWho published the underlying records.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover read-only, idempotent, non-destructive and closed-world, so the bar is lower, yet the description still adds real operational context: no API key is needed, rate limits are shared with the employer lookup, and median offered wage is reported under the site's floors. The only missing pieces are pagination and behavior for unrecognized titles or codes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Information is front-loaded, starting with what the tool returns, and the example sits at the end where it is easy to find. Sentences are dense compound constructions, and the fragment 'No key, under the same shared limits as the employer lookup' is terse to the point of being cryptic, but nothing is padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter lookup with an output schema, the description covers call requirements (no key, shared limits), accepted inputs and the shape of the response including the 2010-to-2018 crosswalk. Nothing essential to a correct invocation is absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the q property already documents accepted SOC code formats (15-1252, 15-1252.00, 151252) and the 2-80 character bound. The description adds only the example query and the equivalent 'job title' framing, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: SOC codes that employers filed a given job title under in DOL's PERM, prevailing wage and LCA files, plus each code's share. It also enumerates what comes back per code (title, O*NET description and tasks, top filing titles, approval rate, median wage) and the 2010-to-2018 crosswalk, so an agent can tell this apart from get_occupation or lookup_employer at a glance.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than stated: an agent infers this is the tool for mapping a job title to SOC codes, and the trailing example {"q":"data scientist"} clarifies the entry point. There is no explicit when-to-use/when-not guidance and no routing versus get_occupation, search_occupations or lookup_employer, even though get_occupation plausibly overlaps on O*NET content.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.