Dice MCP

Job Search

search_jobs

Read-only

Search for job listings by keyword, location, and filters. Returns job details, company info, and application links.

Use this tool when users want to find jobs, search employment opportunities, or explore job openings. DO NOT use for: applying to jobs, submitting applications, or making employment decisions.

LLM USAGE INSTRUCTIONS:

ALWAYS provide the keyword parameter (required)
When presenting results to users, include BOTH the job details URL (detailsPageUrl) AND the company page URL (companyPageUrl) for each job
Use location to find geographically relevant positions
Combine filters to refine searches (e.g., workplace_types=['Remote'] for remote work)
Use posted_date to find recent openings ('ONE'=1 day, 'THREE'=3 days, 'SEVEN'=7 days)
Default jobs_per_page is reasonable, increase for comprehensive searches
Use company_name to scope results to a specific employer
Use sort='datePosted' when the user wants the newest listings instead of the most relevant
Use facets to get aggregate counts (e.g., how many results are remote vs on-site) without paging through all results
After presenting results, do NOT automatically call get_job_details for every job returned. Wait for the user to indicate which specific job(s) they're interested in, then pass that job's guid to get_job_details.

IMPORTANT - AI DISCLOSURE REQUIREMENT: When presenting job search results to users, you MUST include an appropriate disclosure that these results were retrieved using AI assistance. Example disclosure language: "These job listings were found using AI-powered search. Please review all job details carefully and verify information directly with employers before applying."

This tool provides job listing data only. Final employment decisions should always involve human judgment and direct review of complete job postings.

Args: keyword: The job keyword or title to search for (required) location: Geographic location for the job search (city, state, country) radius: Search radius from the specified location (minimum 1, requires radius_unit) radius_unit: Unit for search radius. Options: 'mi', 'km' (requires radius) jobs_per_page: Number of jobs to return per page (1-100, defaults to 5) page_number: Page number for pagination (1-based, default is 1) sort: Sort order for results. Options: 'relevance', 'datePosted' (defaults to relevance) posted_date: Filter by posting date. Options: 'ONE' (1 day), 'THREE' (3 days), 'SEVEN' (7 days) workplace_types: Workplace arrangements. Options: 'Remote', 'On-Site', 'Hybrid' employment_types: Employment types. Options: 'FULLTIME', 'CONTRACTS', 'PARTTIME', 'THIRD_PARTY', 'INTERNSHIP' employer_types: Employer types. Options: 'Direct Hire', 'Recruiter', 'Other' willing_to_sponsor: Filter for employers willing to sponsor work authorization (boolean) easy_apply: Filter for jobs with easy application process (boolean) company_name: Filter by company name fields: Specific fields to include in response (optional, returns all exposed fields by default) facets: Facet dimensions to aggregate (optional). Options: 'employmentType', 'postedDate', 'workFromHomeAvailability', 'workplaceTypes', 'employerType', 'easyApply', 'isRemote', 'willingToSponsor'

Returns: JobSearchResult: Contains: - data: List of JobDisplayFields with job details including: * guid: The job's identifier to pass as job_id to get_job_details for the full description and skills list (NOT the id field, which is a different, internal identifier not accepted by get_job_details) * detailsPageUrl: Direct link to full job posting * companyPageUrl: Link to company profile page * title, summary, salary, location, employmentType, etc. - metadata: Search metadata with pagination info and facet results

Raises: Exception: If API call fails or input validation errors occur

Input Schema

TableJSON Schema

Name	Required	Description	Default
`sort`	No
`facets`	No
`fields`	No
`radius`	No
`keyword`	Yes
`location`	No
`easy_apply`	No
`page_number`	No
`posted_date`	No
`radius_unit`	No
`company_name`	No
`jobs_per_page`	No
`employer_types`	No
`workplace_types`	No
`employment_types`	No
`willing_to_sponsor`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`data`	No	Array of job listings matching the search criteria
`metadata`	No	Metadata about the search results and pagination

TDQS

A4.7/5.0

Behavior4/5

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

Annotations already indicate readOnlyHint=true, but the description adds meaningful behavioral context: it returns listing data only, mandates an AI disclosure to users, and instructs agents to wait for user selection before fetching details. This goes beyond the annotations, though it omits potential rate limits or data freshness details.

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?

The description is long but well-organized with sections (LLM USAGE INSTRUCTIONS, Args, Returns, Raises). It front-loads the purpose and each sentence carries operational value, though some repetition in the usage instructions could be trimmed without loss.

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 search tool with 16 parameters, it covers the search logic, return structure (JobSearchResult with data and metadata), the critical guid-vs-id caveat, pagination, facets, and error handling. With an output schema present, this is complete enough for an agent to use it correctly.

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

Parameters5/5

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

Schema description coverage is 0%, but the description's Args section thoroughly explains all 16 parameters, including allowed values, dependencies (radius/radius_unit), and default behaviors (e.g., posted_date: 'ONE'=1 day). This fully compensates for the schema's lack of descriptions.

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?

Description opens with 'Search for job listings by keyword, location, and filters' – a specific verb+resource that clearly identifies the tool's function. It also differentiates from siblings by explaining that search_jobs is for finding jobs while get_job_details is for retrieving details of a specific job (guid passed to it).

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

Usage Guidelines5/5

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

Explicitly states when to use the tool: 'when users want to find jobs, search employment opportunities, or explore job openings.' It also gives clear exclusions ('DO NOT use for: applying to jobs...') and provides cross-referenced guidance about not automatically calling get_job_details, effectively distinguishing it from the sibling tool.

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

All Dice MCP tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.8/5.0

Disambiguation5/5

Each tool targets a distinct resource and action: search_jobs discovers job listings, get_job_details returns the full description and skills for a specific job, and get_company retrieves company details for a job. There is no overlap in purpose, and descriptions explicitly clarify when to use each tool.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case: search_jobs, get_job_details, get_company. The verbs are semantically appropriate (search for discovery, get for retrieval) and the pattern is uniform across the set.

Tool Count5/5

Three tools is a well-scoped, focused set for a read-only job search MCP. Each tool earns its place in the search → details → company flow, and the count falls comfortably within the typical 3-15 range.

Completeness4/5

The core user journey is covered: searching for jobs, viewing full job details, and looking up company information. Minor gaps exist (e.g., no company search or application submission tools), but these are explicitly outside the stated purpose, so the surface is adequate for the domain.

Resources

Need Help?