This server lets AI assistants search and analyze live Taiwan 104 job listings via MCP tools, including job search, company lookup, job details, company job listings, and applicant analysis.
search_jobs: Search jobs by keyword, location (e.g., Taipei City), salary floor, job category, remote type, full/part-time, experience level, and sort (newest, salary). Supports pagination, excludes ads optionally, and detects company-name queries (returns a hint to use find_company instead).
find_company: Find a company by name (full, short, or English alias) and get its ID, industry, location, employee count, capital, and active job count. Returns a candidate list if multiple matches exist.
get_job_detail: Fetch complete details of a single job using its URL or slug — full JD, salary, location, education/experience requirements, skills, languages, benefits, industry.
get_company_jobs: List all open positions for a specific company, with optional in-company keyword search (matches job title + JD content, OR logic). Supports pagination with limit tiers (20/50/100) and pinned jobs.
get_apply_analysis: Get real applicant statistics for a job (unique applicants in 2 weeks, and distributions by sex, education, age, experience, language, major, skills, certifications) — only when explicitly requested.
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., "@mcp-server-104 搜尋台北市的Rust工程師職缺，月薪6萬以上，排除面議"
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.
An MCP server for Taiwan's 104 Job Bank (104人力銀行). Lets Claude (or any MCP client) search 104's live job listings directly.
Your situation | Best tool |
Occasionally job hunting on your own | Just open the 104 website |
Want to write a one-off crawler to scrape data | A Playwright / cycletls script is enough, no MCP needed |
Want Claude to analyze/compare/summarize/automate job listings | This MCP |
Related MCP server: job104-mcp
Pick one of the following three, depending on which client you use:
A: Clients with quick-command support — one line, config written automatically:
claude mcp add job104 -- npx -y mcp-server-104 # Claude Codecodex mcp add job104 -- npx -y mcp-server-104 # OpenAI Codex CLI（新版才有；舊版走 B 的 TOML）B: Clients where you paste config manually — paste the config into that client's MCP config file:
Claude Desktop / Cursor / Windsurf (JSON):
{
"mcpServers": {
"job104": { "command": "npx", "args": ["-y", "mcp-server-104"] }
}
}OpenAI Codex CLI legacy (~/.codex/config.toml):
[mcp_servers.job104]
command = "npx"
args = ["-y", "mcp-server-104"]A and B do the same thing: tell the client "start this server with npx". The core is
npx -y mcp-server-104everywhere; the only difference is how each client registers it.⚠️ ChatGPT web/desktop cannot connect to this kind of local (stdio) server — it only supports remote URL-based MCP, and there's no machine of yours on its cloud to run
npx.
C: Developers who want to modify the code — after cloning this repo:
npm install && npm run build
claude mcp add job104 -- node /你的路徑/104-mcp-server/dist/index.jsSee "Development" below for daily commands and testing strategy.
104's search API sits behind Cloudflare bot protection. Using curl or Node fetch (even with Referer / User-Agent headers) gets blocked — returning 403 or Cloudflare's "Just a moment..." challenge page.
The key isn't the header, it's the TLS fingerprint. Cloudflare checks the TLS handshake fingerprint (JA3); a normal program's fingerprint clearly isn't a browser and gets blocked outright.
This project uses cycletls to impersonate Chrome's TLS fingerprint, making Cloudflare think the request comes from a real browser → let through. This way no browser is needed (an order of magnitude lighter, faster, and easier to deploy than Playwright / Selenium), and real JSON is obtained over plain HTTP.
cycletls is backed by a Go-based TLS client subprocess, started once when the server launches and shared for the entire session.
Tool | Status | Description |
| ✅ Real data | Search jobs by keyword + multiple filters, with pagination |
| ✅ Real data | Get full details for a single job: complete JD, salary, location, education/experience requirements, skills, language abilities, benefits, industry |
| ✅ Real data | List all open positions at a given company (paginated) |
search_jobs parametersParameter | Required | Description |
| ✅ | Job title keyword, e.g. |
| Work location name, e.g. | |
| Minimum monthly salary (TWD), e.g. | |
| Set | |
| Set | |
| Job category name, e.g. | |
| Remote: | |
| Employment type: | |
| Years of experience required: | |
| Page number (20 per page), default 1. Flip further for more results | |
| Max results returned on this page, up to 20, default 5 |
Implementation details of filter parameters (all derived from observing 104's official site UI requests + verifying against
metadata.total):
salaryMinmust be sent together withscmin+sctp=M+scstrict=1; withoutscstrictthe salary filter is completely ignored."Negotiable" salary value is
0, and 104 keeps these by default (negotiable could be very high).excludeNegotiableremoves them.The salary cap
9,999,999is 104's "no upper limit" sentinel value, normalized server-side to "N and above". The salary prefix follows the originals10type (10=negotiable, 30=hourly, 40=daily, 50=monthly, 60=annual) — part-time jobs are mostly hourly, don't read them as monthly.
remoteWork=1 full/2 partial,ro=1 full-time/2 part-time,jobexp=1/3/5/10/99 (mutually exclusive experience bands).Area/job class use a tree code table + pruning: when a parent node matches (e.g. "新竹縣市"), the parent code is used rather than expanding into a bunch of child codes — expanding too much makes 104 return
400. For areas with the same name in multiple places (e.g. "信義區"), neither union nor search is performed;ambiguousAreais returned for the model to confirm with the user (unioning geographically unrelated places is meaningless). For job classes with multiple matches, union is kept (searching related job classes together is usually what's wanted).Ad detection: 104 stuffs ads at the top of results (raw field
jobType=1), which ignore the keyword (e.g. a nurse search surfaces "COACH 精品銷售"). Each result carries afeaturedflag marking it, andexcludeFeatured=truefilters the whole batch out.jobType=2(paid priority slots) still matches the keyword and is treated as a valid result without the flag. Search listings deliberately omit the full JD (kept lean, to avoid the model mismatching a listing's URL to another entry when summarizing lists); useget_job_detailfor full content.
Field naming is consistent across all three tools (all mapped to 104's original field semantics, avoiding same-name-different-meaning):
Concept
search_jobs
get_job_detail
get_company_jobs
Job code (slug, can be fed back to
get_job_detail)
jobId
jobId
jobIdJob URL
url
url
urlArea (district level)
area
area
areaFull address (district + street)
—
location—
Years of experience required
—
experience
experienceProficient tools/languages (C++, Linux)
skills
skills—
Job skills (job-class level, e.g. "軟體工程系統開發")
—
jobSkills—
Company page URL (feed to
get_company_jobs)
companyUrl
companyUrl—
Whether it's an ad slot (
jobType=1)
featured—
—
Update date (the page's "MM/DD更新")
appearDate
appearDate—
jobIdis always a slug (e.g.7uqyj), not 104's internal number — only the slug can be fed back toget_job_detail.skillsalways means "specific technologies".appearDateis uniformlyYYYY/MM/DD. Company job listings deliberately omit dates: the company API's raw data only has year-less formats like8/20, so stale zombie listings always look recently updated (testing found 2025 listings mixed in), silently misleading across year boundaries — if you want a specific listing's date, feed itsjobIdtoget_job_detailfor the full version.
get_job_detail parametersParameter | Required | Description |
| ✅ | Job URL or code, e.g. |
get_company_jobs parametersParameter | Required | Description |
| ✅ | Company URL or code, e.g. |
| Page number (20 per page), default 1 | |
| Max results returned on this page, up to 20, default 10 |
How the three tools chain together:
Every result from search_jobs / get_job_detail returns two URLs: url (job) and companyUrl (company).
Want the full content of a listing → feed its url to get_job_detail.
Want to see "what else this company has open" → feed companyUrl to get_company_jobs (it's a specific company's job list, not a keyword search).
search_jobs ─ url ──────→ get_job_detail
│ │
└─ companyUrl ───────────┴──→ get_company_jobsMain endpoint:
GET https://www.104.com.tw/jobs/search/api/jobsRequired headers: Referer: https://www.104.com.tw/jobs/search/, Accept-Language: zh-TW
Common query parameters (this project currently only uses a subset; the rest are for future expansion):
Parameter | Meaning | Example value |
| Keyword | Free text |
| Keyword operator |
|
| Sort |
|
| Pagination |
|
| Area code (comma-separated) | Look up |
| Job class code (comma-separated) | Look up |
| Minimum salary | Integer |
| Remote |
|
| Full/part-time |
|
| Experience |
|
| Education |
|
Area / job class code tables (hosted on static.104.com.tw, no Cloudflare protection, retrievable with a plain fetch):
https://static.104.com.tw/category-tool/json/Area.json
https://static.104.com.tw/category-tool/json/JobCat.jsonOther endpoints:
Job detail: GET https://www.104.com.tw/job/ajax/content/{slug} (Referer points to /job/{slug})
Company jobs: GET https://www.104.com.tw/api/companies/{code}/jobs?page=1&pageSize=20 (returns list.topJobs + list.normalJobs)
src/
index.ts 進入點：建 server、掛 tool、接 stdio、處理關閉
config.ts 所有設定 / 魔術數字（JA3 指紋、endpoint、節流區間…）
types.ts 乾淨型別 + normalizeJob / JobDetail / CompanyJob（防腐層）
query.ts 純函式：組查詢網址、client 端過濾、enum 對照
slug.ts 從 104 網址取出職缺 slug / 公司碼（types/query 共用）
codes.ts 地區/職類「名稱→官方代碼」解析（樹狀比對+剪枝，快取代碼表）
api/
httpClient.ts cycletls 單例（TLS 指紋偽裝）
throttle.ts 禮貌性隨機節流 1.5~3.5s
job104.ts 104 抓取層：組 URL → 打 API → 重試 → 正規化
tools/
searchJobs.ts search_jobs
getJobDetail.ts get_job_detail
getCompanyJobs.ts get_company_jobs
scripts/
smoke-test.mjs 手動發 JSON-RPC 驗證，不用開 Claude 也能測
test/
types.test.mjs normalize 邏輯（薪資格式、面議、哨兵值…）
query.test.mjs 組網址 / slug / 公司碼 / 過濾 / enum 對照
codes.test.mjs 代碼表樹狀比對 + 剪枝npm run build # 編譯 src → dist
npm test # 跑單元測試（先 build 再 node --test，零額外依賴）
node scripts/smoke-test.mjs # 煙霧測試（連真實 104）
npm run inspect # 開 MCP Inspector GUI 除錯After changing code, run npm run build, then restart Claude Code (or use /mcp reconnect) for changes to take effect — the client only fetches the tool list once at session startup.
Testing strategy: pure logic (normalize, URL building, filtering) is extracted into types.ts / query.ts and tested with Node's built-in node --test — fast and no network needed, so breakage is caught immediately. Network-touching parts (job104.ts / httpClient.ts) are verified against the real 104 via smoke tests.
104 has no public official API. This project uses unofficial internal endpoints from the web frontend, which may stop working at any time due to 104's changes.
Automated access may violate 104's terms of service. This project is for personal, low-frequency, learning purposes only.
Do not use it for high-frequency scraping, large-scale crawling, or hosting as a public service — you risk being blocked and face legal exposure.
This project has built-in polite rate limiting (random 1.5~3.5 second interval between requests); do not remove or lower it.
Users are solely responsible for any consequences of using this project.
用公司名稱找 104 上的公司，回傳公司名片：companyId（公司代碼，可直接餵給 get_company_jobs）、全名、公司頁網址、產業、地區、員工數、資本額、在徵職缺數。比對是模糊的：英文別名（如 MediaTek）也找得到中文本尊，但 total 含「簡介提及」的公司會偏大。唯一命中或名稱完全相符 → 回單一 company；多家符合 → 回 candidates 候選清單，此時請向使用者確認是哪一家（用產業/地區/在徵職缺數分辨），不要自行猜選。「某公司有沒有某類職缺」的標準流程：find_company 拿 companyId → get_company_jobs 帶 keyword。
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | 公司名稱 —— 全名、常用簡稱或英文名皆可，如 '聯發科'、'台積電'、'MediaTek' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden; it discloses fuzzy matching, the total count caveat for introduction mentions, and the single-vs-candidates decision rule. It does not state what happens when no company matches, which is a minor but relevant gap.
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 action and output, then moves through matching behavior, user-confirmation guidance, and the downstream workflow in a logical order. Every sentence carries operational value with no redundant filler.
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?
For a one-parameter tool with no output schema and no annotations, it covers the input contract, output fields, ambiguous-result handling, and integration with get_company_jobs. The only notable omission is the no-match return behavior; otherwise an agent has enough to call it 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?
The single name parameter is already fully described in the schema with full-name/abbreviation/English examples, so schema coverage is 100%. The description adds extra meaning by explaining alias matching and fuzziness, which helps the agent understand acceptable inputs and edge cases.
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 the tool finds companies on 104 by name and enumerates the returned 'company card' fields, including the companyId that feeds get_company_jobs. This clearly defines the verb+resource and distinguishes it from job-search siblings.
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?
It explicitly prescribes the standard flow for checking whether a company has certain job types (find_company → get_company_jobs with keyword) and tells the agent to confirm with the user rather than guess when multiple candidates appear. It does not explicitly contrast with search_jobs or get_job_detail, but the intended use case is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
列出「某一家指定公司」在 104 上在徵的職缺（職稱、地區、薪資、學經歷要求、網址），可分頁。公司用 find_company 回傳的 companyId，或 search_jobs / get_job_detail 回傳的 companyUrl。帶 keyword 可在這家公司內搜職缺（比對職稱與 JD 內文，含「其他條件」欄 —— 「某公司有沒有 C++」這種問題用它，別自己翻頁過濾職稱）。⚠️ keyword 多字詞是 OR 不是 AND，要同時符合請分次搜再交集。要完整翻頁，limit 請直接用檔位值本身（20、50 或 100）且全程不變 —— 非檔位值的 limit 會截掉每個窗口的尾端且下一頁不補回。置頂職缺（pinned=true）只在第 1 頁回、不佔 limit 名額；total 不含置頂。
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 第幾頁（窗口大小＝limit 所在檔位 20/50/100），預設 1。完整翻頁時 limit 請用檔位值且中途不換 | |
| limit | No | 一般職缺的回傳筆數上限，最多 100，預設 10。想一次拿完（如公司內搜 C++）用 100；要完整翻頁請用檔位值 20/50/100 本身（其他值會截掉窗口尾端）；置頂職缺另計、不佔名額 | |
| keyword | No | 在這家公司內搜職缺的關鍵字（比對職稱與 JD 內文）。例如 'C++'。多字詞是 OR，要 AND 請分次搜再交集 | |
| companyUrlOrId | Yes | 公司代碼或網址：find_company 回傳的 companyId，或 search_jobs / get_job_detail 回傳的 companyUrl。例如 '12noppgo' 或 'https://www.104.com.tw/company/1a2x6blghh' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden, and it covers the critical non-obvious behaviors: complete pagination requires gear-value limits (20/50/100) held constant, non-gear limits silently truncate window tails with no backfill, pinned=true jobs only appear on page 1 without consuming limit quota, and total excludes pinned jobs. These are exactly the traps an agent cannot infer from schema.
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?
Purpose is front-loaded in the first sentence, followed by parameter sourcing, keyword usage, then pagination and pinned-job caveats. The text is dense but every clause earns its place — the ⚠️ warnings cover behaviors that would otherwise cause silent data loss or truncated results.
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?
For a 4-param tool with no annotations and no output schema, the description covers the returned fields, pagination semantics, keyword matching operators, pinned-job behavior, and parameter provenance from each sibling tool. Nothing an agent needs in order to invoke it correctly or interpret results is missing.
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 100%, so every parameter is already documented. The description adds value beyond the schema: the gear-value pagination rule, keyword matching scope (JD 內文含其他條件欄), the OR-not-AND semantics, and the provenance of companyUrlOrId from sibling tool outputs. Only slightly held back by the schema already carrying most parameter details.
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 opens with a precise verb+resource statement: listing a specific company's job openings on 104, with the returned fields enumerated (職稱、地區、薪資、學經歷要求、網址) and pagination noted. It also differentiates from the search_jobs sibling by positioning itself as the company-scoped tool for questions like 'does this company have C++'.
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?
Explicit when-to-use guidance is present: '某公司有沒有 C++' 這種問題用它, 別自己翻頁過濾職稱. It also instructs where to source companyUrlOrId from (find_company, search_jobs, get_job_detail) and warns about keyword OR semantics with the workaround (要 AND 請分次搜再交集). Alternatives and exclusions are stated rather than implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
取得單筆 104 職缺的完整詳情：完整職務說明、薪資、地點、學經歷要求、需求技能、語言能力、福利、產業別。傳入 search_jobs 結果中的職缺網址（url 欄位）。
| Name | Required | Description | Default |
|---|---|---|---|
| jobUrlOrId | Yes | 職缺網址或代碼，例如 'https://www.104.com.tw/job/7uqyj' 或 '7uqyj'（用 search_jobs 回傳的 url） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the behavioral burden itself. It clearly signals a read-only fetch by saying 取得, and it sets expectations about what content will be returned. It does not describe error behavior or not-found cases, which is a minor gap for such a simple fetch tool.
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 only two sentences with no filler. It front-loads the core purpose, lists the content categories, and then gives the input binding instruction. Every sentence contributes value, and structure is clean and scannable.
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?
For a single-parameter read tool with no output schema, the description adequately covers the purpose, the sort of data the agent will receive, and how to construct the input. A small residual gap is the lack of clarification around missing/invalid job URLs, but overall the instruction is complete enough for correct invocation.
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 input schema already provides full parameter documentation at 100% coverage, including format and example and the search_jobs context. The description repeats the instruction to use the url field from search_jobs but does not add substantial new semantic meaning beyond the schema.
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 action and resource: retrieving complete details for a single 104 job, and enumerates the content fields (薪資、地點、學經歷要求、技能、福利 etc.). It references search_jobs for the input URL, which helps distinguish it from the sibling search and company-level tools.
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 description gives explicit workflow guidance: pass the jobUrl from search_jobs results. It tacitly says to use this tool when a single job's complete details are needed rather than the search tool's results, though it does not explicitly exclude alternatives like find_company.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
依關鍵字與篩選條件搜尋台灣 104 人力銀行的即時職缺，回傳職稱、公司、地區、薪資、需求技能與職缺網址。支援地區、薪資下限、職類、遠端、全/兼職、年資篩選，以及分頁。若 area 同名多處（如「信義區」有台北市與基隆市兩個），不會直接搜尋，改回傳 ambiguousArea 候選清單 —— 此時請向使用者確認是哪一個，再用完整名稱（如「台北市信義區」）重新搜尋。limit 只數一般職缺：廣告位（featured=true）另計、不佔名額。要完整翻頁請用 limit=20（上游每頁固定 20 筆一般職缺）；跨頁彙整時用 jobId 去重（最新排序下新缺插入會使分頁窗口飄移）。keyword 適合職務/技能詞；輸入公司名稱時 104 不執行搜尋，本工具會回 companyKeyword 提示 —— 此時請改用 find_company 找到公司，再用 get_company_jobs 取得該公司職缺。
| Name | Required | Description | Default |
|---|---|---|---|
| area | No | 工作地區名稱，例如 '台北市'、'新竹'（會解析成 104 官方地區代碼查詢） | |
| page | No | 第幾頁（每頁 20 筆），預設 1。想看更多職缺就往後翻頁 | |
| sort | No | 排序：newest 最新更新在前（找新開職缺/掃描擴編用，建議搭配 excludeFeatured=true，否則廣告位仍會無視排序卡在最前面）/ salary 待遇由高到低。不給則用 104 預設的相關性排序 | |
| limit | No | 一般職缺的回傳筆數上限，最多 20，預設 5。廣告位（featured=true）另計、不佔名額；要完整翻頁請用 20 | |
| remote | No | 遠端工作：full 完全遠端 / partial 部分遠端 / any 兩者皆可 | |
| jobType | No | 工作性質：fulltime 全職 / parttime 兼職 | |
| keyword | Yes | 職務關鍵字，例如 'Rust 工程師' | |
| salaryMin | No | 月薪下限（新台幣），例如 60000。薪資明確低於此值的濾掉；面議預設保留 | |
| experience | No | 需求年資級距：under-1y(1年以下)/1-3y/3-5y/5-10y/over-10y(10年以上) | |
| jobCategory | No | 職務類別名稱，例如 '軟體工程師'、'行銷企劃'（會解析成 104 官方職類代碼查詢） | |
| excludeFeatured | No | 排除 104 付費推廣/廣告職缺（結果中 featured=true 的），預設 false。這些會被 104 硬塞在最前面、常不符合搜尋條件；想只看自然結果時設 true | |
| excludeNegotiable | No | 排除「面議」（沒寫薪資）的職缺，預設 false。想只看有明確薪資時設 true |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and fully delivers. It discloses non-obvious behaviors: featured ads are excluded from limit and ignore sort order, ambiguous area returns an ambiguousArea candidate list instead of searching, company keywords produce a companyKeyword hint, and newest-sort pagination windows drift and require jobId dedup. This goes well beyond the minimum.
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 long but every sentence earns its place for a 12-parameter tool with no annotations. It is front-loaded with the core purpose, then progressively covers edge cases, pagination, and sibling tool routing. The structure is logical and dense without redundancy.
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?
Given the tool's complexity — 12 parameters, no output schema, no annotations — the description is remarkably complete. It covers return contents, filter semantics, ambiguous routing, ad behavior, pagination and dedup, and company-name fallbacks. An agent has enough information to invoke this tool correctly in nearly all scenarios.
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 100%, which sets a baseline of 3, but the description adds substantial meaning beyond the schema: limit only counts regular jobs while featured ads are separate, salaryMin preserves '面議' by default, sort=newest is best paired with excludeFeatured=true, and keyword is for job titles/skills only — not company names. Each parameter's real-world behavior is clarified.
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 opens with a specific verb + resource: search real-time 104 job bank openings by keyword and filters, and lists the returned fields (title, company, region, salary, skills, URL). It also distinguishes itself from siblings by explicitly routing company-name queries to find_company and get_company_jobs.
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 description gives explicit when-to-use guidance: use find_company then get_company_jobs when the keyword is a company name, and instructs the agent to ask the user for clarification when area is ambiguous. It also provides pagination strategy (limit=20 for full pages, jobId for de-duplication) and suggests excludeFeatured=true for newest sort.
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.2.0find_companyget_company_jobsget_job_detailsearch_jobsScored across 4 tools
Each tool targets a distinct retrieval scope: global job search, fuzzy company lookup, single-job details, and per-company job listings. Even though search_jobs and get_company_jobs both return job lists, the descriptions clearly separate global vs. company-scoped search and include cross-references to guide selection.
All tool names follow a lowercase snake_case verb_noun pattern: search_jobs, find_company, get_job_detail, get_company_jobs. The slight verb variation between search/find/get maps sensibly to different retrieval actions, and there is no mixing of styles or unpredictable naming.
Four tools is a well-scoped size for a focused job-board client. Each tool covers a necessary step in the core workflows—searching jobs, inspecting a job listing, finding a company, and listing a company's jobs—without redundancy or obvious bloat.
The tool surface covers the main job-seeker flows end to end: global filtered search with pagination, detailed job lookup, company resolution by name, and targeted search inside a specific company. The described handling of ambiguous areas, company-name searches, and pagination edge cases closes the important gaps, leaving no dead ends.
Search live startup jobs from Claude, Cursor, or ChatGPT via MCP. Free, no account needed.
JobsPipe — data pipeline of every job posting on the web. Search live, normalized job postings from 30+ ATS feeds and job boards for AI agents via MCP.
Public MCP server for discovering open jobs. Search, filter, and get application links.
MCP for 8,700+ current AI jobs. 13 tools: search, match, salaries, companies, commerce quotes.
