MCP TOOLcubeshell.jobs.find

Job Listings

Use when the user needs current job postings as a hiring signal or for market research. Filter by job title, company name, company website, or location, at least one, plus an optional remote flag. Returns up to 10 postings per page with a page parameter for more. It does not find people or contacts, and it does not apply to jobs; each posting includes its own application link.

At least one real filter

Send at least one of job_title, company_name, company_website or location. has_remote and page are not filters on their own: a call with only those is rejected as INVALID_INPUT before anything is charged.

Request

Workspace identity comes from the authenticated MCP connection, not from the call arguments. There is no workspace field to set.

Parameter	Type	Description
`request_id`required	`string`	Stable idempotency key, 1 to 200 characters. Replaying the same request_id with the same input returns the original result without a second charge.
`quote_only`required	`false`	Must be false. Quote-only preview is not available in this version.
`input.job_title`	`string`	Job title to match. Up to 200 characters.
`input.company_name`	`string`	Hiring company name. Up to 200 characters.
`input.company_website`	`string`	Hiring company website. Up to 500 characters.
`input.location`	`string`	Location to match, such as a city or country. Up to 200 characters.
`input.has_remote`	`boolean \| null`	Optional remote filter. Narrows the results, it does not stand in for a filter above.
`input.page`	`integer`default: 1	Result page, starting at 1. Minimum 1, maximum 1000.
`max_microcredits`	`integer`	Optional ceiling. If the authoritative price is higher, the call is rejected before anything is charged.

tools/call

{
  "name": "cubeshell.jobs.find",
  "arguments": {
    "request_id": "jobs-find-example-001",
    "quote_only": false,
    "input": {
      "job_title": "Account Executive",
      "location": "Berlin",
      "has_remote": true,
      "page": 1
    }
  }
}

Each page is a separate call

Paging is not free browsing. Every page is its own billed call, so walking through ten pages costs ten calls. Narrow the filters until the first page answers the question rather than paging blindly. Read result.total_count and result.total_pages on the first page to decide whether another page is worth it.

Result

On status: "succeeded", the result field holds one page of postings. result.jobs may be null, so check it before iterating.

Parameter	Type	Description
`result.jobs`	`array \| null`	Postings on this page.
`result.jobs[].title`	`string`	Job title.
`result.jobs[].company_name`	`string`	Hiring company name.
`result.jobs[].company_website`	`string`	Hiring company website.
`result.jobs[].company_profile_url`	`string`	Public professional profile URL for the hiring company.
`result.jobs[].location`	`string`	Posting location.
`result.jobs[].description`	`string`	Posting description.
`result.jobs[].experience_level`	`string`	Experience level named on the posting.
`result.jobs[].application_url`	`string`	Where a human applies. Cubeshell does not apply on anyone's behalf.
`result.jobs[].published`	`string`	When the posting was published.
`result.jobs[].remote`	`boolean`	Whether the posting is remote.
`result.jobs[].types`	`array of string \| null`	Employment types, such as full-time. May be null.
`result.count`	`integer`	Postings returned on this page.
`result.page`	`integer`	The page this response covers.
`result.per_page`	`integer`	Postings per page, up to 10.
`result.total_count`	`integer`	Postings matching the filters across all pages.
`result.total_pages`	`integer`	Pages available for these filters.
`result.next_page`	`string`	The next page to request, when there is one. Fetching it is another billed call.
`result.truncated`	`boolean`	True when more postings matched than were returned on this page.

Not found

When no postings match the filters, the call returns status: "not_found" with no result. This is a real terminal status rather than an error, and it is not charged. It is a genuine hiring signal: this company is not hiring for that role right now. An agent should not retry the same filters hoping for a different answer, and should not page past the last page to look for one.

Similar Companies

Web Scrape