MCP Tools
Profile Collection Tools
MCP reference for the agent_profile_collection domain: list, read, select and deselect Agent Profiles — with scopes, parameters and examples.
These tools live in the agent_profile_collection domain — your assistant calls the domain with an action and arguments, as covered in the overview. For the concept behind selection, read Identity & Roles.
List your profiles
| Tool | Scope | Access |
|---|---|---|
| agent-profile_list | agent_profile.list | Read only |
Lists every Agent Profile in your collection — id, display name, short bio, tags and last activity — plus the URL patterns for profile pages and A2A cards.
| Parameter | Type | Required | Notes |
|---|---|---|---|
| agentProfileIds | string[] | No | Filter to specific profile ids. Omit to list everything. |
Call it at the start of a session, or whenever the agent needs to find the right identity for a role. It returns compact summaries, so it’s cheap to call before reading a profile in full.
Read a profile
| Tool | Scope | Access |
|---|---|---|
| agent-profile_read | agent_profile.read | Read only |
Reads a single Agent Profile in full: workspaces, tags, permissions, timestamps, and the link to its A2A agent card.
| Parameter | Type | Required | Notes |
|---|---|---|---|
| agentProfileId | string | No | The profile to read. Defaults to the currently selected profile (“self”); required when nothing is selected. |
Use it before selecting, to confirm a profile is the right fit — its bio, allowed workspaces and permissions. Called mid-session with no arguments, it doubles as a “who am I right now?” check.
Select a profile
| Tool | Scope | Access |
|---|---|---|
| agent-profile_select | agent_profile.select | Write |
Selects an Agent Profile and attaches the session to that identity. From this point, tool calls act on behalf of the profile, its permissions apply, and any on awake instructions saved to the profile are returned for the agent to follow. The selection persists for the client connection until deselected or switched, and the profile’s last-active time updates.
| Parameter | Type | Required | Notes |
|---|---|---|---|
| agentProfileId | string | Yes | The profile to adopt. |
{
"action": "agent-profile_select",
"arguments": { "agentProfileId": "agent-builder-y9vii" }
}
Selection changes what every later call is allowed to do, so it belongs under user or explicit task instruction. Typical trigger: “Select the writing agent profile and draft the release notes.”
Deselect the active profile
| Tool | Scope | Access |
|---|---|---|
| agent-profile_deselect | agent_profile.select | Write |
Disconnects the session from the active Agent Profile: the identity, its context and its permissions are removed, and available actions revert to the baseline connection. Takes no parameters; with nothing selected it simply confirms a clean state.
Use it at the end of a task performed under a specific identity, or before switching to unrelated work. Users can disable deselection for a profile, in which case this action is unavailable.
Where to next
- Profile Admin tools — create a profile worth selecting.
- Profile Actions tools — what a selected profile can actually do.
- Identity & Roles — what happens at the moment of selection, conceptually.