Skip to main content
Glama

Read roles

readJob
Read-onlyIdempotent

Read the company's roles. list: optional lifecycle. Every role with its jobId, position, lifecycle, workplaceType, isComplete. Call it whenever the user names a role or asks how many jobs they have; only open roles accept intro requests. Candidate counts per role come from listPipeline. Refer to roles by position, never show the id. get: jobId. A role's full state: basic fields incl. example profiles (goodFitLinkedinUrls), sourcing brief, active requirements, interview stages, locations with ids, job memory. Read before any edit, especially before set_brief, set_stages or set_requirements. list_questions: jobId. The role's screening questions with ids, text, explanation, type, priority, optional and hidden flags. list_locations: jobId. Current locations with ids. get, list_questions and list_locations need a jobId from list.

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": "readJob"
  }
}

Input Schema

NameRequiredDescriptionDefault
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.
commandYesWhich operation to run: list | get | list_questions | list_locations. The tool description explains each.
lifecycleNolist (optional): only roles in this lifecycle. create (optional, default draft): set 'open' when the role details are ready for sourcing.

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.6/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: the open-roles-only rule for intro requests, the display rule 'Refer to roles by position, never show the id', and a note that Clera privately records inputs and results for usage tracking. Rate limits and payload size are not addressed, keeping it short of a 5.

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 per-command keying ('list:', 'get:', 'list_questions:', 'list_locations:') front-loads the structure and makes it scannable, and the closing sentence on jobId sourcing is a useful tying rule. It is dense but every clause carries information; the privacy boilerplate is the only line that could be called boilerplate.

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 four-command multiplexed read tool this is complete: every command's return fields are described, the prerequisite chain is stated, an output schema exists so return formatting needs no further explanation, and cross-tool shortcuts (listPipeline for candidate counts) are called out. An agent could invoke any command correctly without opening the schema.

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 coverage is 100%, so baseline is 3, but the description goes further by mapping each parameter to a command (jobId only for get/list_questions/list_locations; lifecycle only for list) and by telling the agent to resolve jobId via list. The orgId parameter is left entirely to its schema description, which is the main gap.

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?

Opens with a specific verb+resource ('Read the company's roles') and then decomposes the four commands (list, get, list_questions, list_locations) with the exact fields each returns, so an agent knows precisely which sub-operation yields what. It also distinguishes itself from siblings by naming listPipeline as the source for candidate counts and by noting edit-related tools require a prior get.

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?

Gives explicit trigger conditions ('Call it whenever the user names a role or asks how many jobs they have'), a sequencing rule ('Read before any edit, especially before set_brief, set_stages or set_requirements'), and a dependency rule ('get, list_questions and list_locations need a jobId from list'). It also states a domain constraint that changes behavior: only open roles accept intro requests.

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