Cerulean Jobs

Find similar jobs

find_similar_jobs

Read-onlyIdempotent

Use this when someone wants more roles like one specific Cerulean listing: the closest open roles by what the job is and where it is. Takes that listing's id, not keywords. If the listing is unknown or has no similarity data, it returns an error rather than unrelated results.

Input Schema

TableJSON Schema

Name	Required	Description
`id`	Yes	The id of the listing to find roles like, as every result carries it, or its URL on a Cerulean site. It is not among its own results.
`limit`	No	How many similar roles to return, up to 20. Defaults to 12.
`locale`	No	The user's language and region, as a BCP 47 tag: fr-CH for someone writing French in Geneva, say. It sets the language of titles and descriptions, and adds localizedUrl, the listing on that locale's Cerulean site, where the site carries it. It does not filter: country and location do. Cerulean's sites are en: ceruleanjobs.com, English, worldwide; fr-FR: cerulean.fr, French, France; fr-CH: ceruleanjobs.ch, French, Switzerland; de-CH: ceruleanjobs.ch, German, Switzerland; en-CA: ceruleanjobs.ca, English, Canada; fr-CA: ceruleanjobs.ca, French, Canada; de-DE: ceruleanjobs.de, German, Germany; en-GB: ceruleanjobs.co.uk, English, UK; es-ES: cerulean.es, Spanish, Spain; it-IT: ceruleanjobs.it, Italian, Italy. Any other tag takes its language's site, so fr-BE reads as fr-FR and en-US as en; another language reads as en. Defaults to en.
`offset`	No	How many to skip, for the next page. Defaults to 0, maximum 10000.
`country`	No	Keep only similar roles in this country.
`location`	No	Keep only similar roles in this city, region or country.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	Yes
`offset`	Yes
`hasMore`	Yes
`results`	Yes
`warnings`	No
`similarTo`	Yes
`indexBuiltAt`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedSep 25, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already cover readOnly, idempotent, and destructive hints, so the description's main contribution is the error behavior: it returns an error for unknown listings or missing similarity data instead of unrelated results. This adds useful behavioral context beyond the annotations, though it doesn't detail output format (covered by the output schema).

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

Conciseness5/5

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

The description is two sentences with no fluff. It front-loads the core purpose and usage, then adds the error behavior, which is essential for the agent to set expectations. Every sentence earns its place.

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?

Given the output schema exists and the input schema fully documents all 6 parameters, the description provides sufficient context for correct invocation: it clarifies the input type (id), the error case, and the general behavior. Nothing critical is missing for an agent to use the tool correctly.

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%, so all parameters are already documented with detailed descriptions (e.g., id, limit, locale, offset, country, location). The description adds minimal extra meaning beyond what the schema provides, mainly reinforcing that the id is a listing id, not keywords. This meets the baseline for full schema coverage.

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 clearly states the tool's purpose: finding similar jobs based on a specific listing's id, distinguishing it from keyword-based search. It uses a specific verb ('find') and resource ('similar jobs'), and explicitly notes it takes an id, not keywords, which separates it from the sibling 'search' tool.

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

Usage Guidelines4/5

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

It gives explicit when-to-use context ('when someone wants more roles like one specific Cerulean listing') and describes error behavior for invalid input. It doesn't explicitly name alternatives like 'fetch' or 'search', but the 'not keywords' phrasing implies when not to use it, making the guidance clear enough.

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

All Cerulean Jobs tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?