Skip to main content
Glama

Create or edit a role

editJob
Destructive

Create and edit the company's roles. create: one of position (blank role), jobUrl (posting link) or jobText (pasted JD). Returns the jobId. Only when the user explicitly asks for a new role. Then run get, name the missing fields and hand over the getDashboardLink role_preview link. update: jobId + updates. Only provided fields change. lifecycle open publishes the role and starts matching, which needs employmentType, a salary bound and an experience bound. set_brief: jobId + brief. Markdown sourcing brief for Clera's matching team, never shown to candidates; full replace, null clears. set_roles: jobId + roles. 1 to 3 job-category tags, required for matching; the roles field says which tags belong. set_stages: jobId + stages. Ordered interview stages, full replace, matched by name. A stage with candidates on it can't be removed or renamed here; hand over the getDashboardLink role_preview link instead of retrying. add_requirements: jobId + requirements. Discrete, evaluable criteria the contact stated, e.g. "must have payments experience". Appends; vague preferences go to update_memory. update_memory: jobId + memoryUpdates. Record a note the moment the contact says something durable about this role, without being asked. Null deletes a key. create_question: jobId + question and optional fields. Returns the full list. update_question: jobId + questionId + fields to change. Returns the full list. delete_question: jobId + questionId. Returns the full list. set_requirements: jobId + requirements. Full replace; omitted requirements are removed. Returns the list. add_location: jobId + normalizedLocation, e.g. 'Berlin, Germany', geocoded strictly; reformulate if rejected. add_remote_location: jobId + code. 'worldwide', a region or country slug, for remote roles. remove_location: jobId + locationId. Returns the full list with ids. Ids come from readJob (list, list_questions, list_locations) or from create.

Clera privately records this tool's inputs and results for usage tracking and support.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "command": "<command>"
    },
    "name": "editJob"
  }
}

Input Schema

NameRequiredDescriptionDefault
codeNoadd_remote_location (required): a canonical remote code: 'worldwide' for anywhere, a region slug (e.g. 'eu', 'north-america'), or a country slug (e.g. 'germany', 'united-states'). Use this for remote roles instead of geocoding a city.
briefNoset_brief (required): the full job brief as structured markdown with ## sections like Ideal Profile, Must-Haves, Nice-to-Haves, Red Flags, Green Flags, Target Companies, Compensation, Interview Process. Replaces the entire brief. Pass null to clear the brief entirely.
jobIdNoEvery command except list and create (required): the job's UUID. Resolve it with list.
orgIdNoOrganization to act as. Only needed when you belong to more than one organization.
rolesNoset_roles (required): 1 to 3 job-category tags from Clera's role list for the work this hire does day to day, e.g. ["AE", "Sales"] for a closing sales role. A name not on the list is refused with the list. Synonyms of that category count; adjacent categories do not: a sales role never gets Business Development, Growth or Account Manager. Every tag widens candidate search, so an extra tag pulls in people from that other category.
jobUrlNocreate (one of position, jobUrl, jobText): a careers-page or job-posting link. The server scrapes it, parses the posting into a full role, and detects duplicates.
stagesNoset_stages (required): ordered list of interview stages, full replace, priority follows array order. Stages are matched by name, so a rename reads as a removal plus an insert. Moving candidates off a stage is done on the dashboard, where the company picks their new stage.
commandYesWhich operation to run: create | update | set_brief | set_roles | set_stages | add_requirements | update_memory | create_question | update_question | delete_question | set_requirements | add_location | add_remote_location | remove_location. The tool description explains each.
jobTextNocreate (one of position, jobUrl, jobText): the full pasted job description text. The server parses it into a full role.
updatesNoupdate (required): the role fields to change, only provided fields are written. Includes the candidate-facing description, lifecycle, pay (base salary and OTE), experience, visa, workplace, hiringManagerContactId, calendarLink, applicationFormUrl and goodFitLinkedinUrls.
optionalNocreate_question, update_question (optional): whether the candidate may skip this question.
positionNocreate (one of position, jobUrl, jobText): job title, e.g. 'Senior Backend Engineer'. Use this to start a blank role you fill in yourself.
priorityNocreate_question, update_question (optional): display order, lower shows first.
questionNocreate_question (required), update_question (optional): the question text shown to the candidate.
lifecycleNolist (optional): only roles in this lifecycle. create (optional, default draft): set 'open' when the role details are ready for sourcing.
locationIdNoremove_location (required): the location's id from list_locations.
questionIdNoupdate_question, delete_question (required): the screening question's id, from list_questions.
descriptionNocreate (optional): initial job description. Only meaningful with position; a jobUrl/jobText create derives the description from the parsed posting. Markdown: ## per section, - per list item, blank line between paragraphs. Keep posting's sections + wording.
explanationNocreate_question, update_question (optional): why the question is asked. Pass null to clear it.
questionTypeNocreate_question, update_question (optional): answer input type. Defaults to TEXTAREA when omitted.
requirementsNoadd_requirements (required): requirements to add, each becomes a separate row in the dashboard
memoryUpdatesNoupdate_memory (required): memory entries to upsert, a null value deletes the key
normalizedLocationNoadd_location (required): a physical place as free text, e.g. 'Berlin, Germany'. The server geocodes it and rejects input that resolves to no place.

Output Schema

NameRequiredDescriptionDefault
jobNo
jobsNo
briefNo
jobIdNo
stagesNo
commandYes
entriesNo
messageYes
diffBlockNo
locationsNo
questionsNo
stageCountNo
requirementsNo
assignedRolesNo
fieldsUpdatedNo
alreadyExistedNo

Schema Changelog

Changes observed during successful MCP inspections.

No schema history has been recorded yet.

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare destructiveHint=true and non-idempotent, and the description adds much beyond them: which sub-operations are full replaces vs appends, that null clears a field or deletes a memory key, that a stage rename reads as removal plus insert, that geocoding rejects input that must be reformulated, and the return shape for each list-returning command. It also discloses the private usage-tracking/data-recording behavior, which annotations cannot convey.

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?

It is long, but length is justified by 14 distinct commands, and it is front-loaded with create/update before the narrower setters. The main weakness is that the command walkthrough is an undifferentiated prose block rather than visually separated entries, which makes scanning for one command slower than it needs to be.

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 23-parameter, deeply nested mutation tool with an output schema and full annotations, the description covers prerequisites, replacement semantics, return values, and failure handling (geocode rejection, in-use stages). Nothing an agent needs to pick the right command or avoid a destructive mistake appears to be missing.

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

Parameters4/5

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

Schema description coverage is 100%, so the baseline is 3, but the description adds cross-field meaning the schema cannot express: lifecycle 'open' requires employmentType plus a salary bound and an experience bound before matching can start, and jobIds must be resolved via readJob or returned from create. It stops short of documenting every nested update field, which the schema already handles well.

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 opens with a clear verb+resource ("Create and edit the company's roles") and then enumerates all 14 commands with specific objects (set_brief = markdown sourcing brief, set_roles = 1-3 job-category tags, add_requirements = discrete evaluable criteria). It also distinguishes itself from siblings by naming readJob as the id source and getDashboardLink's role_preview link as the escalation path.

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?

Explicit when-to-use conditions are given per command, including the guard "Only when the user explicitly asks for a new role" and the follow-up procedure (then run get, name missing fields, hand over the role_preview link). It also routes correctly between close alternatives: vague preferences go to update_memory while discrete criteria go to add_requirements, and a stage with candidates must not be retried but escalated to the dashboard link.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources