AyHire

Find people for a role

find_people_for_role

Run the role's own search and save everyone it finds to the role. A role with a search plan (search_plan in get_role: the role's mix, tools and 3-6 searches read from its brief) runs every search in it: repos about the work, repos using the tools, profiles that say the job, and the tools' own maintainers (kept apart as builders). Each search is answered from AyHire's own index of people first and searched live on GitHub only where the index is thin or older than a month. Each person comes with why_found, source (index or GitHub just now) and a relevance (area fit, the brief's similarity, quality, feedback). Older roles run one search: people behind the top repos matching its words and language. role. People the role has already seen are left out, so each round brings new people (include_seen to bring them back); page 2 and on read the next repos. Returns everyone found with name, company, location, GitHub 'hireable' flag, followers, the matching repos they build and how much. To choose people yourself instead, use the search tools with role_id (search_people, find_people_behind_repos, search_commits) and add_people_to_role. Nothing is scored yet: call score_role_person for the people worth a closer look. Free (GitHub only). Pass query/language to search differently this time. For rounds that learn from your feedback (decide with reasons) and keep the plan's required constraints, use next_round.

Input Schema

Name	Required	Description
`page`	No	Page of matching repos (default 1)
`query`	No	Override the search words for this run, e.g. 'vector database' (optional)
`role_id`	Yes
`language`	No	Override the repo language for this run, e.g. 'Rust' (optional)
`location`	No	Keep only people whose GitHub location is in one of these places: cities, countries or regions (Europe, US, North America, UK). Profile searches use GitHub's location filter, so local people are found, not just filtered; people there come first.
`include_seen`	No	Also return people the role has already seen (default false)
`location_unknown`	No	With location: people who list no location. auto (default) keeps them only when at least 3 people matched the places; include always keeps them after the matches; exclude never does. location_filter.note says when few or none matched.

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?

The annotations mark this as non-read-only, open-world, non-idempotent, and non-destructive; the description goes further by explaining that it saves people to the role, runs the search plan, queries the index first and GitHub live when needed, excludes already-seen people, pages through matching repos, and returns why_found/source/relevance. These details are consistent with the annotations.

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 front-loaded with the core action and most sentences add relevant behavioral or usage context. It is dense and somewhat run-on, but given the tool's complexity and the number of alternatives it needs to distinguish, the length is mostly justified.

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 complex 7-parameter tool with no output schema, the description is complete enough: it explains what is searched, how index versus live GitHub results work, what is returned, what is not done yet, and which sibling tools to use for adjacent tasks.

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 high at 86%, so the schema already carries most parameter documentation. The description still adds useful semantics beyond the schema: query/language override the search for this run, include_seen brings back people the role has already seen, and page 2 onward reads the next repos.

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 states a specific verb and resource: run the role's own search and save everyone it finds to the role. It clearly distinguishes this from manually choosing people with search_people/find_people_behind_repos/search_commits plus add_people_to_role, and from next_round for feedback-learning rounds.

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 explicit when-to-use guidance and alternatives: use this tool to run the role's saved search, use the search tools with role_id plus add_people_to_role to choose people yourself, call score_role_person afterward for scoring, and use next_round for feedback-driven rounds with required constraints.

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

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