update_agent

Edit an Agent definition by its caller-relative name: bare with a standalone personal credential, me/name for private content in organization scope, or <team>/name for a bound team. A bare organization-scoped name denotes the read-only organization catalogue. Changing normalized behavior appends a new immutable active version; changing only metadata does not.

Parameters

Parameter	Type	Required	Description
name	string	Yes	Current address: bare with a standalone personal credential, me/name in private org space, or <team>/name.
new_name	string	No	New bare name without a scope prefix.
description	string	No	Replacement description.
definition	object	No	Complete replacement definition; see create_agent for its shape.
version_limit_policy	string	No	Change retention behavior to reject or prune_oldest.

Omission leaves a field unchanged. Explicit JSON null has the same meaning as omission; it does not clear a field.

Response

Field	Type	Description
id	string	Stable internal definition identifier.
name	string	Effective canonical qualified name, including a rename.
active_version	integer	Current active version after the update.

Example

{
	"name": "engineering/reviewer",
	"new_name": "security-reviewer",
	"definition": {
		"identity": "You review code with a security-first mindset.",
		"categories": [],
		"components": []
	}
}

Result:

{
	"id": "018f...c2a1",
	"name": "engineering/security-reviewer",
	"active_version": 2
}

Errors

In addition to the definition-validation errors documented for create_agent:

Code	Cause
agent_not_found	No Agent remains at the requested name in the target space, including if it was renamed while this call was pending.
agent_name_taken	new_name already exists in that ownership space.
agent_version_limit_reached	Behavior changed, the version limit is reached, and policy is reject.
empty_name	The current name is empty after removing the team prefix.
forbidden	The credential lacks update authority, uses me/ outside organization scope, or targets the read-only organization catalogue.
team_not_found	No team with that prefix is bound to this credential.
personal_cannot_address_team	A standalone personal credential used a Team prefix.
no_personal_space	A userless organization credential used me/name.
invalid_arguments	Input is missing or does not match the schema.
internal_error	An unexpected server error occurred.

Notes

• The tool is governed: it requires Tools and tool-policy admission. A standalone personal target additionally requires its Agent-update permission; a Team target requires a binding and the matching Team permission; me/name requires an acting user with active organization membership.
• After a rename, the old qualified name no longer resolves. Use the name returned here.
• Later get_agent, bootstrap, and agent_context calls read the current active version.
• The organization catalogue is not an MCP mutation target.