Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@h1b-sponsor-mcp Is Stripe still sponsoring H-1Bs for data roles in New York?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Ask Claude "is this company still sponsoring H-1Bs?" and get a straight answer in tables, built from 1.28 million public government filings plus USCIS approval records.
An MCP server for job seekers who'll need visa sponsorship. It combines all three public sponsorship signals for each employer, shows how they've moved over the last six months against the same months a year earlier, and runs locally on a database that updates each quarter.
You: Compare Microsoft, Amazon, Google, Meta, Apple, Nvidia and TCS for data scientist sponsorship.
Claude: (calls compare_companies)Company | LCAs Jan–Jun 2026 | of which new employment | vs a year earlier | PERM certified, last 12 mo | USCIS new-employment approvals FY2025 | USCIS denial rate FY2025–FY2026 to Q3 | Still sponsoring? |
Microsoft Corporation | 351 | 152 | -15% | 147 | 1,394 | 🟢 2.6% | 🟢 Yes, active |
Amazon.com Services LLC | 616 | 334 | +32% | 1 | 4,637 | 🟢 1.3% | 🟢 Yes, active |
Google LLC | 240 | 150 | +8% | 0 | 1,042 | 🟢 1.2% | 🟢 Yes, active |
Meta Platforms, Inc | 386 | 210 | +2% | 9 | 1,554 | 🟢 1.3% | 🟢 Yes, active |
Apple Inc. | 137 | 67 | +69% | 3 | 827 | 🟢 1.1% | 🟢 Yes, active |
NVIDIA Corporation | 7 | 0 | +75% | 8 | 560 | 🟢 0.7% | 🟢 Yes, active |
TATA CONSULTANCY SERVICES LIMITED | 1 | 0 | — | 0 | 846 | 🟡 6.1% Elevated | 🟡 Occasional |
Real output, data through Jun 30, 2026. LCA and PERM columns are filtered to data-scientist roles; the USCIS columns are company-wide.
That one table answers three questions most sponsorship sites can't. Is the company still filing this year, and in which direction? And will it take you through to a green card? Amazon and Google are filing plenty of H-1Bs for data scientists, but certified almost no green-card (PERM) cases for them in the last 12 months. And how often does USCIS turn this employer down? TCS's 6.1% denial rate is more than twice the national 2.5%, so it's flagged.
Tool | Example question |
| "Is Stripe still sponsoring? Just data roles in New York." |
| "Compare Databricks, Snowflake and Stripe." |
| "Who sponsors machine learning engineers in Georgia?" |
| "What do H-1B data scientists get offered in Atlanta, by level?" |
| "Which Deloitte entities file separately?" |
| "What data is this based on, and how current is it?" |
Every answer is a markdown table that names its date window ("Jan–Jun 2026", never just "last 6 months") and says what the numbers do and don't mean.
Every verdict and flag starts with a signal, so a table reads at a glance: 🟢 good · 🟡 caution · 🔴 warning · ⚪ not enough data. The word after the signal says the same thing, for anyone reading without emoji.
Related MCP server: h1b-mcp
You need uv. The package is on PyPI. The first run downloads the database (about 61 MB compressed) and caches it; after that everything is local and offline.
Claude Desktop: add to claude_desktop_config.json:
{
"mcpServers": {
"h1b-sponsor": {
"command": "uvx",
"args": ["h1b-sponsor-mcp"]
}
}
}Claude Code:
claude mcp add h1b-sponsor -- uvx h1b-sponsor-mcpAny other MCP client works the same way: run uvx h1b-sponsor-mcp over stdio. To run the newest code from GitHub instead of the PyPI release, use uvx --from git+https://github.com/janishkumar/h1b-sponsor-mcp h1b-sponsor-mcp.
Signal | Source | What it tells you | Coverage |
H-1B LCAs | DOL Labor Condition Application disclosures | The freshest signal: an employer is preparing H-1B petitions. Split into new employment (e.g. from F-1/OPT) and transfers from other employers. | Decisions Oct 2024 – Jun 2026 (1.02M filings) |
Green cards | DOL PERM disclosures | Whether the company sponsors permanent residence | Decisions Oct 2024 – Jun 2026 (259K cases) |
Confirmed petitions | USCIS H-1B Employer Data Hub | Approvals and denials by petition type, per fiscal year | FY2023 – FY2026 Q3 |
How current is it? DOL publishes each quarter about 5–6 weeks after it ends, so the data is between 1.5 and 5 months old at any time. Every H-1B site uses these same files, so none can be fresher. Windows are anchored on the newest decision in the data, not today, so "last 6 months" is always a fully covered window.
What an LCA is not. An LCA is a filing an employer makes before an H-1B petition. It covers new hires, renewals and transfers, and some never become petitions. Treat LCA counts as an upper bound on sponsorship activity. The USCIS columns are the confirmed side.
Denial-rate flags. Each employer's USCIS denial rate over the last full fiscal year plus the current one is compared with the national rate over the same years (2.5% for FY2025–FY2026 Q3):
Flag | Rule | Where that sits |
🔴 High | 3× national or more (7.6%+) | 5.5% of the 5,159 employers with 20+ decisions |
🟡 Elevated | 2× national or more (5.1%+) | a further 3.1% |
🟢 Normal | below 2× | the median employer is 1.6% |
Both flags need at least 20 decisions and 3 denials, so a single denial at a small firm doesn't produce a scary flag. New-employment petitions (the F-1/OPT → H-1B route) get their own rate in company_sponsorship. USCIS doesn't publish job titles, so denial rates are company-wide even when you filter by role.
"Still sponsoring?" is a rule, not a model. It looks at certified LCAs in the last 6 months against the same months a year earlier:
Verdict | Rule |
🟢 Yes, active | 5+ filings, and not down by half or more |
🟡 Slowing sharply (−x%) | at least 10 filings a year earlier, and down 50% or more |
🟡 Occasional | 1–4 filings |
🔴 No filings in last 6 months | none in 6 months, some in the last 12 |
🔴 No recent sponsorship | none in 12 months |
flowchart LR
A[DOL LCA xlsx<br/>5 files, 1 GB] --> C[Standardise<br/>de-duplicate by case number<br/>drop contact details]
B[DOL PERM xlsx] --> C
U[USCIS crosstab<br/>UTF-16 export] --> C
C --> E[Employer resolution<br/>names + federal tax IDs]
E --> D[(sponsors.duckdb<br/>111 MB)]
D -->|gzip, GitHub release| R[Release asset]
R -->|downloaded once,<br/>update check daily| S[MCP server<br/>stdio, read-only]Employer names are messy. Names that file under a shared federal tax ID are merged: "Amazon.com Services LLC", "AMAZON.COM SERVICES LLC", "Amazon Web Services, Inc." and "Amazon Development Center U.S., Inc." count as one employer. Two guards stop bad merges. A tax ID shared by more than 12 names is almost always a payroll provider, so it's ignored. And a name only joins a tax ID's cluster if its first word matches the main filer's. 1.28M filings resolve to 156,896 employers.
Search matches whole leading words. "Amazon" finds Amazon.com Services, Amazon Web Services and Amazon Data Services, and lists them, so you can see exactly what was counted. If a name catches something unrelated ("Apple" also matches Apple Tree Dental), find_employer gives you the exact name to pass instead.
No personal data ships. The source files include employer contact names, emails and phone numbers, plus attorneys and preparers. The build drops all of it, and a test checks that the published database contains none of those columns.
Lean runtime. The server installs only mcp, duckdb and platformdirs. Answers take under a second.
Tax IDs alone over-merge. The first build merged everything that ever shared a tax ID, and "Amazon" came back with TechCorp Solutions Inc. in it: a small firm whose 21 filings list one of Amazon's tax IDs, almost certainly a keying error. A name now joins a tax ID's cluster only if its first word matches the main filer's. A regression test covers it.
"Last 6 months" was off by a day. Subtracting six months from June 30 lands on December 30, so the first window read "Dec 2025–Jun 2026". Windows are now whole calendar months (Jan–Jun 2026 vs Jan–Jun 2025), with tests for month-end and mid-month anchors.
Prefix search catches neighbours. "Apple" also matches Apple Tree Dental. Fuzzy brand matching would hide that rather than fix it, so every answer lists the entities it counted, and find_employer gives you the exact name to narrow it.
The government sites block scripts. The plan was a scheduled GitHub Action that refreshed the data every quarter. DOL and USCIS both return 403 to automated downloads, and DOL's official data API (45 datasets) doesn't carry LCA or PERM. So the download stays a two-minute browser step, and everything around it is automated: a watcher that says when and what to download, a gated make refresh, and a weekly health check of the published release.
I checked what already existed before building this. As of October 2026:
This server | Hosted connectors (Pipeworx, MCPBundles) | |||
LCA filings | ✅ 21 months | ✅ one quarter at a time | via H1BGrader | ✅ |
USCIS approvals and denials | ✅ by petition type | — | — | — |
Green-card (PERM) filings | ✅ | — | — | — |
Trend vs. a year earlier | ✅ | — | — | — |
Employer names merged via tax ID | ✅ | — | — | — |
Runs locally and offline | ✅ | downloads raw files on demand | scrapes a third-party site | hosted |
DOL publishes a new quarter about six weeks after it ends. DOL and USCIS refuse scripted downloads, and DOL's data API doesn't include these datasets, so one step stays human: about two minutes in a browser each quarter. Everything else is automated:
flowchart LR
W[Watcher<br/>1st and 15th of release months] -->|new data found| N[Notification with<br/>exact files to get]
N --> H[You: download 2-3 files<br/>into ~/Downloads]
H --> R[make refresh]
R --> C[collect, retire old years]
C --> B[rebuild]
B --> G{quality gates}
G -->|fail| X[stop, nothing published]
G -->|pass| D[before/after diff, confirm]
D --> P[GitHub release]
P --> U[users' servers update within a day]
P --> HC[weekly health check in CI]Piece | What it does |
Watcher (scheduled task) | Twice a month in release months, reads the DOL and USCIS pages in a browser and compares them with the published release. Says exactly which files to download, or that nothing's new. |
| Moves recognised files from |
Quality gates | The data must move forward. Filings in the period both builds cover must change by less than 2% (a bigger drop means a file went missing). Employer count stays plausible, Microsoft, Amazon and Google are all present, nothing has columns that look like contact details, filings resolve to employers, and all six tools answer. |
Weekly health check ( | Downloads the published release the way users do and runs the same checks, plus a staleness check (fails if the data is more than 200 days old). A failure emails the maintainer. |
Manual steps, if you'd rather not wait for the watcher:
From the DOL performance data page, download the newest LCA_Disclosure_Data_FY… and PERM_Disclosure_Data_FY… files.
From the USCIS H-1B Employer Data Hub, use Crosstab View → the last four fiscal years → Download → CSV.
Run make refresh and enter the USCIS quarter when asked (e.g. FY2026 Q4).
make setup && make test59 tests run on a synthetic fixture with one planted example of each case: a company that's slowing, one that's steady, one that's stopped, a payroll-provider tax ID, a duplicate case number, a non-H-1B visa class, and a contact-email column that must not survive the build. They also start the real server over stdio and call it as an MCP client would, and they run the refresh pipeline end to end with the gates both passing and failing. CI runs on Python 3.11–3.13, checks that the wheel installs without the build extras, and runs a dependency audit and secret scan.
Code and data are released separately. Data releases are GitHub releases tagged data-YYYY-MM-DD, and the server downloads the newest one. Code releases are version tags: bump the version in pyproject.toml and server.json, then push a tag like v0.1.1, and release.yml publishes to PyPI and the MCP registry through trusted publishing, with no stored tokens.
This is public filing data. It can't tell you whether a particular team will sponsor a particular role, and policies change. Ask the employer.
Is a company still sponsoring H-1Bs, and how much? Returns trend tables.
Shows certified H-1B LCA filings for the last 6 months, the fiscal year so far and the
last full fiscal year (each vs the same period a year earlier), split into new
employment and transfers; green-card (PERM) certifications; USCIS petition
approvals/denials by fiscal year; and a denial-rate flag (Normal / Elevated / High)
relative to the national rate. Point out a High or Elevated flag to the user.
Args:
company: Employer name as people say it, e.g. "Microsoft", "Amazon", "JPMorgan".
role: Optional job filter, e.g. "data scientist", "machine learning",
"software engineer". Matches job title and occupation title.
state: Optional two-letter worksite state, e.g. "GA".
city: Optional worksite city, e.g. "Atlanta".
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | ||
| role | No | ||
| state | No | ||
| company | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish a safe read operation (readOnlyHint=true, openWorldHint=false), so the bar is lower, and the description adds real value on top: it discloses the comparison structure (each period vs the same period a year earlier), the split into new employment vs transfers, and the Normal/Elevated/High denial-rate categorization with a directive to surface elevated results. What it does not cover — caching, data recency cutoff beyond 'last 6 months' — is minor for a read-only lookup.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the user-facing question, followed by the return scope, then a clean Args block. The middle enumeration is dense and semicolon-chained, and the fragment 'Returns trend tables.' adds little given the detail that follows, but nothing is wasted overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although an output schema exists and return values need not be spelled out, the description supplies enough about the returned periods, breakdowns, and denial-rate flag for an agent to interpret and act on results. All four parameters are documented and the one required parameter is obvious from the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry the full burden and largely does: it explains that 'company' should be the employer name as people say it with three concrete examples, that role matches both job title and occupation title, and that state/city are worksite filters with format examples. Only minor gaps remain (no guidance on partial vs exact company matching behavior).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with the exact question the tool answers ('Is a company still sponsoring H-1Bs, and how much?') and then enumerates the specific artifacts returned: H-1B LCA filings by period, PERM certifications, USCIS petition approvals/denials, and a denial-rate flag. This is distinguishable from siblings like top_sponsors or compare_companies, which imply ranking or multi-employer comparison rather than single-employer trend detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The question framing gives clear context for when to invoke it (a single-company sponsorship question), and it adds an explicit behavioral instruction: 'Point out a High or Elevated flag to the user.' It stops short of naming when to prefer a sibling such as compare_companies for multi-employer questions, so it is clear context without explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare employers side by side: filings, trend, green cards, denial-rate flag, verdict.
Args:
companies: Two or more employer names, e.g. ["Stripe", "Databricks", "Snowflake"].
role: Optional job filter, e.g. "data scientist".
state: Optional two-letter worksite state.
city: Optional worksite city.
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | ||
| role | No | ||
| state | No | ||
| companies | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds what the comparison surfaces (denial-rate flag, verdict), but says nothing about matching behavior for unknown employers, result limits, or cost — modest added value against an already-declared read-only profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded summary sentence followed by a compact Args block; nothing is padded. The Args entries restate schema titles but earn their place by adding examples and format hints absent from the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists so return values need no explanation, and annotations cover safety. Combined with full per-parameter documentation, the definition is nearly complete; the only gap is behavior when an employer name isn't found or how many companies are practical in one call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry the burden — and it does: each of the four params is explained, with an example list for companies and a format constraint ('two-letter worksite state') for state. It falls short of 5 because it doesn't say whether company names must match exactly or how partial/fuzzy names are handled.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (compare) and resource (employers), and enumerates what is compared: filings, trend, green cards, denial-rate flag, verdict. The 'side by side' framing distinguishes it from single-employer siblings like company_sponsorship and find_employer, though those siblings are never named.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied by the 'two or more employer names' requirement — an agent can infer this is the multi-employer tool. There is no explicit when-to-use/when-not guidance and no routing against find_employer or company_sponsorship for single-employer lookups.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Which data the answers come from, the dates covered, and the caveats.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds that the response includes caveats and date coverage, which is meaningful disclosure about content, but it does not clarify whether the info is global to the dataset or specific to a prior query.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single compact clause with no filler, and the three returned elements are front-loaded. It loses a point only for being a sentence fragment without a leading verb, which slightly blunts immediate parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists and there are no parameters, so the description carries a light burden, and it names the three content areas returned. However, it never states that the tool takes no arguments or that it describes the whole dataset rather than a specific result, leaving a small interpretive gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; an empty schema leaves no semantic gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description conveys the content returned (data provenance, date coverage, caveats) but is a noun-phrase fragment with no verb, so the action (retrieve metadata about the dataset) must be inferred. It gives no differentiation from siblings like company_sponsorship or salary_range, which is the main gap.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use guidance, no mention of prerequisites, and no reference to any sibling tool. An agent must guess that this is the metadata/provenance call to make before or alongside the data-returning siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the legal employer entities a name matches, so you can pick an exact one.
Args:
query: Start of the employer name, e.g. "Deloitte" or "Amazon Web Services".
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description does add a genuine behavioral trait beyond annotations: matching is by prefix ('Start of the employer name'), which tells the agent a partial substring will not work, and 'legal employer entities' signals entity-level rather than trade-name results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core purpose is front-loaded in one sentence and the docstring-style Args block adds real value via examples. Slightly verbose formatting, but no sentence is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return values need no explanation, and the single parameter is fully described. What remains missing is only the downstream workflow context (which sibling consumes the resolved entity), a minor gap for a one-param lookup.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the schema only says 'Query' is a string, so the description carries the full burden. It does so adequately: prefix-match semantics plus two concrete examples ('Deloitte', 'Amazon Web Services') make the expected input unambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'List the legal employer entities a name matches', plus the follow-on intent ('pick an exact one'). It is clearly a name-resolution lookup, distinct from siblings like company_sponsorship or compare_companies, though it never names those siblings explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The clause 'so you can pick an exact one' implies this is a disambiguation step before calling a detail tool, but that workflow is only implied. There are no explicit when-not conditions and no sibling tools are named as alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Offered H-1B wages for a role (percentiles and by experience level), last 12 months.
Args:
role: Job, e.g. "data scientist", "software engineer".
state: Optional two-letter worksite state.
city: Optional worksite city.
company: Optional employer to restrict to.
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | ||
| role | Yes | ||
| state | No | ||
| company | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish that this is a read-only, closed-world lookup, so the bar is lower. The description still adds meaningful dataset context beyond annotations: the wages are 'offered H-1B wages' rather than general salaries, the data covers 'last 12 months,' and results include percentiles and experience-level breakdowns.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and then gives a compact, well-structured parameter list. Every sentence and argument line earns its place without unnecessary preamble.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value structure need not be explained. The description covers dataset scope, timeframe, and all parameters adequately. Minor gaps remain around data-source limitations and how filters combine, but an agent has enough information to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden of explaining parameters. It defines all four: role with examples, state as a two-letter worksite state, city as worksite city, and company as an employer restriction. It could go slightly further on interactions such as state plus city, but the semantics are largely covered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific resource and scope: offered H-1B wages for a role, with percentiles, experience-level breakdowns, and a 12-month window. This is clearly distinct from sibling tools like company_sponsorship or top_sponsors, though it does not explicitly name or contrast those alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied by the description and optional parameter labels. There is no explicit guidance on when to choose this tool over siblings such as compare_companies or company_sponsorship, nor are there exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rank employers by certified H-1B filings (with denial-rate flags), for a role and place.
Args:
role: Optional job filter, e.g. "data scientist", "data engineer".
state: Optional two-letter worksite state, e.g. "GA".
city: Optional worksite city, e.g. "Atlanta".
months: Look-back window in whole months ending at the latest data (1-21).
limit: Number of employers to return (max 100).
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | ||
| role | No | ||
| limit | No | ||
| state | No | ||
| months | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds genuinely new behavior context — the data source (certified H-1B filings), the presence of denial-rate flags, that the look-back window ends at the latest available data, and the max-limit boundary. It stops short of describing output shape, but an output schema exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core behavior is front-loaded in one sentence, and the Args block is a compact, scannable list with zero filler. Given the empty schema descriptions, each parameter line earns its place rather than restating structured data.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description need not explain return values, and the read-only safety profile is already in annotations; together with full parameter semantics this is nearly complete. The only missing piece is how multiple filters combine and any guidance on choosing this tool versus its siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry the full burden, and it does: every one of the five parameters gets meaning plus concrete examples ('data scientist', 'GA', 'Atlanta') and hard bounds (months 1-21, limit max 100). Without this block an agent could not set 'months' or 'state' format correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence gives a concrete verb and resource — 'Rank employers by certified H-1B filings' — plus the scoping dimensions ('for a role and place') and an extra signal ('denial-rate flags'). An agent can distinguish this from a single-employer lookup like find_employer, though no sibling is named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied through 'for a role and place' and the optional parameters; there is no explicit statement of when to choose this over find_employer, company_sponsorship, or compare_companies. The reader must infer that this tool produces a ranked list rather than a single-company profile.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0company_sponsorshipcompare_companiesdata_infofind_employersalary_rangetop_sponsorsScored across 6 tools
Each tool has a clearly distinct purpose: metadata, single-company sponsorship, multi-company comparison, sponsor rankings, salary ranges, and employer-name resolution. Although compare_companies overlaps conceptually with calling company_sponsorship multiple times, the boundary is explicit and unlikely to cause misselection.
All names use snake_case and are readable, but they mix verb-led names (compare_companies, find_employer) with noun-phrase names (data_info, company_sponsorship, salary_range) and an adjective-led name (top_sponsors). The naming is understandable but not a predictable verb_noun pattern.
Six tools is a well-scoped set for H-1B sponsor research, with no obviously redundant tools. Each tool covers a meaningful operation without bloating the surface.
The set covers company sponsorship, comparisons, rankings, salary ranges, metadata, and employer-name resolution, which is strong lifecycle coverage for a read-only data lookup server. Minor gaps remain around raw filing-level detail or broader employer search beyond prefix-based entity resolution, but core workflows are covered.
Which US employers sponsor H-1B visas? Approvals, denials and sponsor lead lists.
H-1B MCP — US H-1B visa sponsorship & wage data from DOL Labor Condition Application (LCA)…
PERM, prevailing wage and H-1B case status, DOL's queue and the visa bulletin, from federal records
H1B visa salary disclosures + compensation benchmarks — real numbers, not estimates.