list_teammates: Discover Teammates by Role, Skill, or Repo

Reference for the list_teammates MCP tool — how to filter registered teammates by role, skill, or repository ownership, with input parameters and example output.

list_teammates lets your agent discover who is registered on the relay and what they own. Before sending a handoff you can use it to find the right recipient — for example, to answer “who owns apps/web/?” or “which teammate has react as a skill?”. The tool calls agents/list on the relay and returns public Agent Card fields only. No API keys, no inbox counts, and no notification webhook URLs are ever included in the response.

Natural language examples

“List all backend teammates.”

“Who owns the apps/web/ directory?”

“Find a teammate with the react skill.”

“Show me all teammates with the mobile role.”

“Which agents have tailwind in their skills?”

Input parameters

All three filters are optional. When you omit all of them, list_teammates returns every registered active teammate.

role · string

Filter teammates by role. Exact match against the role field registered in the Agent Card — for example, "backend", "frontend", "mobile". Case-sensitive.

skill · string

Filter teammates who have this value in their skills array. The relay performs a GIN-indexed array containment check, so it is efficient even for large teams. Example: "react", "postgres", "terraform".

repo · string

Filter teammates whose repos_owned array contains this value. Matched as an exact array element — for example, "apps/web/". To find who owns a path you can also try a prefix like "packages/".

Output fields

teammates · Teammate[] · required

Array of matching registered teammates. Empty array when no teammates match the filters.

Show Teammate fields

handle · string · required

Teammate’s unique identifier on the relay, in name@team format — for example, frank@acme. Pass this as the to parameter in handoff_to_teammate.

name · string · required

Display name as registered — for example, "Frank — Frontend".

role · string · required

Teammate’s declared role — for example, "frontend", "backend", "mobile".

skills · string[] · required

List of skills declared in the Agent Card. Empty array if none were registered.

repos_owned · string[] · required

Repository paths or directories this teammate owns. Empty array if none were registered.

Example output

{
  "teammates": [
    {
      "handle": "frank@acme",
      "name": "Frank — Frontend",
      "role": "frontend",
      "skills": ["react", "tailwind", "next.js"],
      "repos_owned": ["apps/web/", "packages/ui/"]
    },
    {
      "handle": "carol@acme",
      "name": "Carol — Docs",
      "role": "docs",
      "skills": ["technical-writing", "openapi"],
      "repos_owned": ["docs/", "README.md"]
    }
  ]
}

Finding the right recipient

A common pattern is to call list_teammates first to confirm the handle, then pass it directly to handoff_to_teammate:

“Find who owns apps/web/, then send them a handoff about the new design tokens.”

Your agent resolves the handle from the list_teammates result and uses it as the to parameter — no guessing, no typos in handles.

Teammates update their own Agent Card (skills, repos_owned, role) via PUT /agents/me/card or by re-running agentrelay install. If the list looks stale, ask the teammate to update their card.