> ## Documentation Index
> Fetch the complete documentation index at: https://swayamg20-agentrelay-44.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<ParamField body="role" type="string">
  Filter teammates by role. Exact match against the `role` field registered in the Agent Card — for example, `"backend"`, `"frontend"`, `"mobile"`. Case-sensitive.
</ParamField>

<ParamField body="skill" type="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"`.
</ParamField>

<ParamField body="repo" type="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/"`.
</ParamField>

## Output fields

<ResponseField name="teammates" type="Teammate[]" required>
  Array of matching registered teammates. Empty array when no teammates match the filters.

  <Expandable title="Teammate fields">
    <ResponseField name="handle" type="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`.
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Display name as registered — for example, `"Frank — Frontend"`.
    </ResponseField>

    <ResponseField name="role" type="string" required>
      Teammate's declared role — for example, `"frontend"`, `"backend"`, `"mobile"`.
    </ResponseField>

    <ResponseField name="skills" type="string[]" required>
      List of skills declared in the Agent Card. Empty array if none were registered.
    </ResponseField>

    <ResponseField name="repos_owned" type="string[]" required>
      Repository paths or directories this teammate owns. Empty array if none were registered.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example output

```json theme={null}
{
  "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.

<Tip>
  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.
</Tip>