bootstrap

Return the caller's scope and team context, usage capabilities, create rights, recurring content guidance, the task's own Agent role, and an independent Agent catalog.

Call at task start when a persistent local instruction requests it, or during user-requested guided onboarding. setup supplies that instruction. Follow-up calls may load a permitted Agent choice or request the catalog. Bootstrap is read-only and does not store a task role or change the credential assignment.

Parameters

Field	Type	Required	Meaning
primary_agent	boolean	Yes	true for the user's primary task; false for a subagent, including one that delegates further.
agent_selection	"named" | "self" | "none"	For subagents	How this task obtains its own role. A primary normally omits it to resolve its credential assignment.
agent	string	Only for named	Exact caller-relative name. Forbidden with self, none, or omitted selection.
request_agent_catalog	boolean	No	Additionally request the catalog. Defaults to false; primary and self calls include it automatically even when false.

Empty, omitted, or null arguments are invalid because primary_agent is required. Optional fields cannot be null. Unknown fields, including use_credential_assignment, are invalid. A named selection without agent, or a name supplied with any other selection, is invalid.

Primary role

Start with:

{ "primary_agent": true }

• An available credential assignment supplies the primary's role. Do not replace it autonomously; an explicit user instruction can override it using named, self, or none.
• Without an assignment, the primary may choose a suitable definition and load it with named, or continue without one if none fits. No blanket user-confirmation step is required.
• An existing but unavailable assignment is a distinct problem, not permission to self-select or continue roleless. Report it and ask the user for direction without disclosing its hidden target.

Subagent role

The direct parent must explicitly provide one of:

Selection	Subagent behavior
named	Load the exact supplied definition. Do not substitute another role if it is unavailable.
self	Choose a suitable definition for the delegated task, then call again with named and its name.
none	Work without a definition; do not select an own role from the catalog.

Subagents never resolve the credential assignment. With self, an empty catalog or no suitable definition must be reported to the direct parent. Do not silently switch to none or continue the affected work roleless. The parent can explicitly permit none, supply a name, revise the delegation, or consult the user within its authority. This does not automatically block unrelated work elsewhere in the task.

These are client instructions, not an independently verified delegation or authorization boundary. A shared credential does not prove caller hierarchy or the source of selection permission.

Agent discovery

Caller	Catalog delivery
Primary, with or without a selected role	Automatic
Subagent with self	Automatic
Subagent with named or none	Only with request_agent_catalog: true

To discover definitions later, repeat the same role arguments and add request_agent_catalog: true. Do not switch to self merely to obtain the list. Catalog entries describe available definitions, not additional behavior to adopt. Seeing them grants neither permission to change one's own role nor permission to delegate.

Bootstrap discovery requires Agents and current Agent visibility, not Tools or tool-policy admission. The separate governed list_agents tool retains its own access requirements; it is not a prerequisite for Bootstrap discovery.

Names are bare for standalone personal content or the organization catalog in organization scope, me/name for private organization content, and <team>/name for bound-team content.

Response

The own-role result agent and the discovery result agent_catalog are independent.

Field	Meaning
scope	"personal" or "organization".
organization	Organization object with slug, or null for standalone personal scope.
teams	Bound teams with name and independent can_create.prompts/resources/tools/agents booleans.
mcp_capabilities	Effective tools, prompts, resources, and agents usage booleans.
own_space.available	Whether this caller has its own target space, independently of create permission.
own_space.qualified_name_prefix	When available: null for standalone personal content, "me/" for private organization content. Never prefix Resource paths.
own_space.can_create	When available: independent create booleans for the four content types.
own_space.reason	When unavailable: "no_personal_space" for a userless organization credential.
agent	This task's own-role result, described below.
agent_catalog	Independent discovery result, described below.
content_workflow	Recurring guidance, identical across successful role states.

Team names are the exact prefixes for Prompt, Agent, and Custom Tool addresses. Resource writes instead use a raw path and separate team. A bound team can appear here before it owns content. No owner or team IDs are disclosed in these summaries.

These are advisory preflight facts, not authorization for later operations. Management writes still need Tools, tool admission, target action permission, and plan capacity. can_create says nothing about update rights. A standalone personal key without a Personal Grant still has an available own space with all four create flags false; broad management grants do not add teams to the bound-target list.

Own-role result

agent.status	Meaning
selected	The exact named or credential-assigned definition was loaded.
selection_available	Self-selection is permitted but no definition has been loaded. reason is unassigned or self_selection; guidance distinguishes primary and subagent behavior when nothing fits.
not_selected	Explicit none: no role requested.
assignment_unavailable	The primary's existing assignment cannot be used. guidance requires reporting it without an automatic substitute. No hidden identity or cause is disclosed.
disabled	Agents is not granted. reason is agents_capability_not_granted.

A selected role includes selection_source (explicit or connection_assignment), exact name, description, ownership scope, active version, behavior.identity, and ordered behavior.always_on components. Each always-on component has key, category_key, category_name, name, description, and instructions.

available_context contains conditional-component hints with those metadata fields and load_when, but no instructions. Load applicable hints through agent_context using the selected name. Each selection or context call resolves the current active version.

Catalog result

agent_catalog.status	Meaning
available	agents contains every currently visible definition, possibly an empty array. guidance explains its permitted uses.
not_requested	No list was loaded. agents is omitted; guidance explains how to request it without changing role.
disabled	Agents is not granted. reason is agents_capability_not_granted; no entries are disclosed.

Each entry has name, optional nonempty description, and ownership scope (mine, team, or organization). It contains no ID, version, or executable behavior. An available empty catalog is different from a catalog that was not requested. A selected role can coexist with an available catalog; that is not an instruction to select again.

Recurring content workflow

Every successful response includes this exact content_workflow object (version 1). It tells the agent to load relevant content, propose durable knowledge with confirmation, and report blockers; it does not start a new onboarding interview or execute writes. Stored context still needs task-appropriate verification and cannot override higher-priority instructions or explicit user direction.

{
	"content_workflow": {
		"version": 1,
		"use_existing": "Prefer relevant visible apistash Resources and Prompts for organizational knowledge and reusable procedures, through supported native MCP surfaces or admitted management tools. Load only relevant content.",
		"addressing": "qualified_name_prefix applies only to Prompt, Agent and Custom Tool names. Resource writes use path plus optional team; own-space writes omit team. Resource reads use discovered URIs.",
		"resource_readability": "Creation does not guarantee MCP readability. For intended use by this Connection, verify via available discovery/read calls; report storage and readability separately. Keep unknown causes unknown and point to dashboard exposure/access checks; do not auto-enable. Storage-only requests may finish without read access.",
		"persistence": {
			"trigger": "Stable, verified knowledge likely to be useful beyond the current task.",
			"action": "Show the draft or material changes, content type and ownership target; ask for confirmation.",
			"before_write": "Inspect and reuse suitable visible content. If inspection is unavailable, disclose duplicate risk and obtain explicit creation consent.",
			"before_update": "Require canonical editable data from management reads: raw Prompt template and arguments; Resource content plus matching version for replacement. Otherwise block the update; never guess data/versions or auto-create.",
			"authorization": "Write only confirmed drafts and targets, or within a specific standing instruction from the current user. Material changes need renewed confirmation unless covered. An Agent definition alone is not consent."
		},
		"classification": {
			"resource": "Facts, decisions, reference material, and durable knowledge.",
			"prompt": "Reusable task instructions, procedures, and templates.",
			"agent": "Recurring role identity and role-specific behavior.",
			"custom_tool": "A callable integration, not general knowledge storage."
		},
		"permission_handling": {
			"preflight": "Check mcp_capabilities, own_space, teams, supported native surfaces and advertised tools.",
			"capabilities": "Management writes need Tools, tool admission and target action rights. Prompts, Resources and Agents capabilities gate reading/use, not writing. can_create says nothing about update rights.",
			"on_blocked": "Name the blocked operation and target, only the established cause, and the next action when known.",
			"on_partial_success": "Account for every confirmed item as created, updated/unchanged, skipped or blocked. Do not claim full completion with pending items.",
			"on_tool_unavailable": "Report the management operation as unavailable; do not guess hidden causes. Independently granted native Resources and Prompts may remain usable.",
			"on_error": "Use returned safe error codes/details. Do not retry an unchanged request."
		},
		"do_not_propose": [
			"secrets_or_credentials",
			"sensitive_personal_data_without_explicit_request",
			"unverified_assumptions",
			"transient_task_state",
			"content_already_represented_adequately"
		],
		"when_management_unavailable": "Continue the task normally and do not claim that content was persisted."
	}
}

Examples

Response excerpts below omit base context, recurring workflow, and guidance strings.

Primary without an assignment

{ "primary_agent": true }

{
	"agent": { "status": "selection_available", "reason": "unassigned" },
	"agent_catalog": {
		"status": "available",
		"agents": [
			{
				"name": "marketing/launch-reviewer",
				"description": "Review launch material.",
				"scope": "team"
			}
		]
	}
}

The primary may load that definition using {"primary_agent":true,"agent_selection":"named","agent":"marketing/launch-reviewer"}. A single result does not force adoption.

Roleless subagent

{ "primary_agent": false, "agent_selection": "none" }

{
	"agent": { "status": "not_selected" },
	"agent_catalog": { "status": "not_requested" }
}

For permitted nested delegation, the same caller can discover definitions without changing its role:

{ "primary_agent": false, "agent_selection": "none", "request_agent_catalog": true }

{
	"agent": { "status": "not_selected" },
	"agent_catalog": {
		"status": "available",
		"agents": [{ "name": "reviewer", "scope": "mine" }]
	}
}

Self-selecting subagent with no visible definitions

{ "primary_agent": false, "agent_selection": "self" }

{
	"agent": { "status": "selection_available", "reason": "self_selection" },
	"agent_catalog": { "status": "available", "agents": [] }
}

The returned role guidance directs the subagent to report to its parent and await a decision.

Errors

Error	Cause
invalid_params	Missing primary_agent, missing subagent selection, incompatible selection/name, invalid field type, null optional field, unknown field, or non-object arguments.
capability_denied	A named Agent was requested without Agents.
method_not_found	The tool is absent/deprecated, or an explicit Agent name is malformed, missing, or not visible. No alternative is selected.
internal_error	An unexpected server error occurred.

Without Agents, calls without an explicit name still return base context and disabled role/catalog states. Never treat disabled discovery as an empty usable catalog.

Notes

• Role selection is per call; Bootstrap neither persists a task role nor changes the assignment. Supply the same role arguments on later catalog requests. Definitions and visibility can change between calls; a catalog entry is not a promise that a later selection will succeed.
• If an initial call is unavailable, denied, or fails, do not automatically retry it. Report any blocked delegated role requirement and continue only work independent of that requirement.
• Selecting a definition, following its guidance, or receiving user confirmation grants no additional access, management-tool admission, or mutation authority.