Semata

Build sourcing query

build_sourcing_query

Read-only

Build a reviewable sourcing query from a natural-language brief and, optionally, a role's criteria. Always build a query before sourcing and show it to the user for review. This does not search for people. Resolve named employers with resolve_company first. To revise a reviewed query, use edit_sourcing_query instead of building again, unless the role, the brief or the kind of person wanted has changed. Use strategy archetype for people defined by what they did or were, such as founders, former military officers or career changers, rather than by employer. Requires OAuth.

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>"
    },
    "name": "build_sourcing_query"
  }
}

Input Schema

Name	Required	Description
`q`	No	A short free-text phrase describing the people to find.
`cities`	No	Cities the candidates should be based in.
`roleId`	No	Role whose criteria and target companies shape the query, from list_roles. Omit for a query based on the brief alone.
`country`	No	Country the candidates should be based in.
`schools`	No	Schools or universities the candidates attended.
`allRoles`	No	Job titles the candidates should have held at any time.
`keywords`	No	Up to eight specialties or skills to emphasise.
`strategy`	No	target_companies (default) filters on the role's target employers or the named employers. archetype finds a kind of person by what they did or were, such as founders, former military officers or career changers, and ignores the role's target employers unless workedAtCompanyNames names some. Use archetype when the brief describes a background rather than an employer pool, or when the employer pool has not produced the right people.
`workspaceId`	Yes	The workspace id returned by list_workspaces. Use 'personal' for the personal workspace.
`currentRoles`	No	Job titles the candidates should hold now.
`minTenureMonths`	No	Preferred minimum months in at least one role.
`seniorityLevels`	No	Seniority levels to target.
`maxExperienceYears`	No	Maximum total years of experience. Replaces the role's range, so set it only from a range the recruiter stated.
`minAvgTenureMonths`	No	Preferred minimum average months per role.
`minExperienceYears`	No	Minimum total years of experience. Replaces the role's range, so set it only from a range the recruiter stated.
`workedAtCompanyNames`	No	Employers the candidates should have worked at, using the names returned by resolve_company. Overrides the role target companies.
`workedAtCompanySlugs`	No	LinkedIn company slugs returned by resolve_company for the employers above. Never invent a slug.
`summaryOfCandidateRequirementsNotInRole`	No	Any other requirement from the brief that the role criteria and the fields above do not already capture.

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 28, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations declare readOnlyHint and non-destructive, and the description meaningfully extends this by clarifying that the tool produces a query for review rather than searching for people, and that OAuth is required. It could say more about what the returned query looks like or whether it is persisted, but it already covers the main behavioral traits an agent needs.

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 description is dense but front-loaded: the primary action and review requirement come first, followed by exclusions, prerequisites, and the alternative tool. The strategy archetype sentence slightly repeats the schema's own enum description, but overall every sentence contributes operational guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 18-parameter builder with no output schema, the description covers the critical workflow context: it is a non-searching review step, requires OAuth, depends on resolve_company for employer names, and has a dedicated revision tool. The main residual gap is not describing the shape of the returned query or how to present it, but the annotation and workflow context make this largely adequate.

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 description coverage is 100%, so all 18 parameters are already documented in the schema. The description adds some conceptual nuance around strategy archetype versus target companies, but it does not explain the interaction of roleId with the many filter parameters or guidance for using the location and tenure filters. Baseline 3 is appropriate when the schema does the heavy lifting.

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?

States a specific verb and resource (build a reviewable sourcing query) and immediately distinguishes it from siblings: it does not search for people, and edit_sourcing_query is the tool for revisions. An agent can place it precisely in the sourcing workflow without opening any schema.

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 sequencing (always build before sourcing, show the user for review), prerequisites (resolve employers with resolve_company first), and a named alternative with its selection condition (edit_sourcing_query unless the role, brief, or kind of person changed). It also explains when to choose the archetype strategy versus target_companies, leaving little to inference.

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?