MCP TOOLcubeshell.role.find

People Search

Use when the user knows a job title and a company and needs the person currently in that role. Requires the job title plus the company domain (preferred) or company name. Returns the first matching person or a not_found result. It does not list many people (use cubeshell.employee.find), fetch a known person's profile (use cubeshell.person.profile), or find contact details.

Job title plus a company

job_title is always required. On top of it, send company_domain (preferred, because a domain identifies a company exactly) or company_name. A job title with no company is rejected as INVALID_INPUT before anything is charged. The call returns the first matching person only, not a ranked list of candidates.

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`required	`string`	The role to look for, such as Head of Engineering. Up to 200 characters.
`input.company_domain`	`string`	Bare company domain such as example.com. Not a URL. Up to 253 characters.
`input.company_name`	`string`	Company name, used when you have no domain. Up to 200 characters.
`max_microcredits`	`integer`	Optional ceiling. If the authoritative price is higher, the call is rejected before anything is charged.

tools/call

{
  "name": "cubeshell.role.find",
  "arguments": {
    "request_id": "role-find-2026-07-17-001",
    "quote_only": false,
    "input": {
      "job_title": "Head of Engineering",
      "company_domain": "example.com"
    }
  }
}

Result

Parameter	Type	Description
`result.full_name`	`string`	Full name of the person found in the role.
`result.first_name`	`string`	Given name.
`result.last_name`	`string`	Family name.
`result.job_title`	`string`	The title actually held, as reported. It can be worded differently from the job_title you asked for.
`result.company_name`	`string`	Company the person was matched at.
`result.company_website`	`string`	Website of that company.
`result.profile_url`	`string`	Professional profile URL for the person. Pass it to cubeshell.person.profile for full details.

Not found

When nobody matches the title at that company, the call returns status not_found. That is a real terminal status, not an error, and it is not charged. Agents should not retry a not_found hoping for a different answer. A different wording of the title, or a domain instead of a name, is a new question worth asking. The same question asked twice is not.

Person Details

Company Contacts