Semata

Source candidates

source_candidates

Run a reviewed sourcing query once and save the matching people to Semata's sourced candidate pool. It returns at most 20 people per call. Only call it after the user has reviewed the query from build_sourcing_query or edit_sourcing_query and explicitly asked to source it. Default to 10 people per call. 20 is the maximum per call, so a larger request takes several narrower searches. Pass the query unchanged. People you already sourced for the same workspace and role are excluded, and every request is audited. Returns candidate summaries, a total, and a status of matches or no_match; a failure is an error, never an empty result. Add chosen candidates to a role with add_sourced_candidates_to_screening. Requires OAuth and a workspace role that can edit.

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": {
      "workspaceId": "<workspaceId>",
      "pdlQuery": "<pdlQuery>"
    },
    "name": "source_candidates"
  }
}

Input Schema

Name	Required	Description
`limit`	No	People to return. Defaults to 10; at most 20.
`roleId`	No	Role the search is for, from list_roles. Scopes the exclusion of people already sourced and the audit trail. Use the role the query was built for.
`sandbox`	No	Test dataset option available to super admins only; other callers get an error. Leave false.
`pdlQuery`	Yes	The exact sourcing query returned by build_sourcing_query or edit_sourcing_query. Pass it unchanged.
`workspaceId`	Yes	The workspace id returned by list_workspaces. Use 'personal' for the personal workspace.

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 28, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true), it discloses that already-sourced people for the same workspace and role are excluded, that every request is audited, that a failure is always an error and never an empty result, and that OAuth plus an edit-capable workspace role are required. That is substantive behavioral context an agent cannot get from the structured fields.

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?

Content is front-loaded: purpose, per-call ceiling, precondition, exclusions, return shape, next step, auth. It is slightly repetitive about the 20-person ceiling ('at most 20 people per call' followed by '20 is the maximum per call'), which could have been said once.

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?

With no output schema, the description supplies the return contract (candidate summaries, a total, and a status of matches or no_match), the error semantics, and the auth/permission requirements. Nothing an agent needs in order to call this correctly on the first try is 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: the query must be passed unchanged, and the 20-per-call ceiling means larger requests require several narrower searches rather than pagination. The limit default/max restates the schema, which is minor redundancy rather than added value.

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 specific verb and resource: run a reviewed sourcing query and persist the matches into Semata's sourced candidate pool. It is clearly distinct from build_sourcing_query and edit_sourcing_query, which only produce or modify the query, and from add_sourced_candidates_to_screening, which is named as the downstream step.

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?

It gives an explicit precondition (only after the user has reviewed the query from build_sourcing_query or edit_sourcing_query and explicitly asked to source it) and an explicit next step (add_sourced_candidates_to_screening). The four filtering siblings are effectively routed: build/edit the query first, source here, screen later.

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

All Semata 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?