@spec activate(ArchAstro.Client.t(), String.t()) ::
  {:ok, ArchAstro.Types.AgentTool.t()} | {:error, ArchAstro.Error.reason()}

Activate an agent tool

Transitions a tool from "draft" status to "active", making it available for the agent to use during runs. Only tools in "draft" status can be activated; calling this on an already-active tool is a no-op that returns the current tool state.

Activation validates that all required configuration is present. For built-in tools, this means the builtin_tool_key must resolve to a registered tool type and any required integration must be connected. Returns 422 if prerequisite checks fail.

Requires app scope. The authenticated caller must own the tool's parent agent.

The updated tool with status: "active".

@spec catalog(ArchAstro.Client.t()) ::
  {:ok, [ArchAstro.Types.BuiltinToolCatalogEntry.t()]}
  | {:error, ArchAstro.Error.reason()}

List built-in tool categories

Returns the full catalog of built-in tool categories available on the platform. Each entry describes a tool type that can be added to an agent, including its key, display label, configuration schema, and the individual tools it exposes to the LLM.

The catalog is global — it is not filtered by app or agent. Use the key from each entry as the builtin_tool_key when creating a built-in tool. Entries whose requires_integration is true require a connected integration before the tool can be activated on an agent.

Requires app scope.

Array of built-in tool catalog entries, one per registered tool category.

@spec deactivate(ArchAstro.Client.t(), String.t()) ::
  {:ok, ArchAstro.Types.AgentTool.t()} | {:error, ArchAstro.Error.reason()}

Deactivate an agent tool

Transitions a tool from "active" status back to "draft", removing it from the set of tools the agent can use during future runs. Calling this on a tool that is already in "draft" status is a no-op that returns the current tool state.

Deactivation does not delete the tool or its configuration. To remove the tool permanently, use the delete endpoint.

Requires app scope. The authenticated caller must own the tool's parent agent.

The updated tool with status: "draft".

@spec delete(ArchAstro.Client.t(), String.t()) ::
  {:ok, :ok} | {:error, ArchAstro.Error.reason()}

Delete an agent tool

Permanently removes a tool from the agent. This action cannot be undone.

Both "draft" and "active" tools can be deleted. If you only want to stop the agent from using a tool without removing it, use the deactivate endpoint instead.

Requires app scope. The authenticated caller must own the tool's parent agent.

Empty response. Returns HTTP 204 on success.

@spec get(ArchAstro.Client.t(), String.t()) ::
  {:ok, ArchAstro.Types.AgentTool.t()} | {:error, ArchAstro.Error.reason()}

Retrieve an agent tool

Returns the tool identified by tool. The tool must belong to an agent owned by the authenticated app.

Use this endpoint to inspect a tool's current configuration, status, and metadata. To retrieve all tools for an agent or app, use the list endpoint. Requires app scope.

The requested tool.

@spec list(
  ArchAstro.Client.t(),
  ArchAstro.Types.Operations.GetApiV1AgentTools.Params.t()
) ::
  {:ok, ArchAstro.Types.AgentToolListResponse.t()}
  | {:error, ArchAstro.Error.reason()}

List agent tools

Returns all tools for the authenticated app, optionally filtered by agent or tool kind. Both explicitly created tools and tools derived from connected integrations (installation-sourced tools) are included in the response.

Installation-sourced tools appear with source: "installation" and status: "active". They are synthesized at request time from connected integrations and do not have a persistent tool ID of the atl_... form; their id is a composite of the installation ID and server tool type.

Use the agent filter to retrieve tools for a specific agent. Supplying an agent ID that does not belong to the authenticated app returns 404. Requires app scope.

List of tools matching the supplied filters.

@spec update(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.PatchApiV1AgentToolsTool.Input.t()
) :: {:ok, ArchAstro.Types.AgentTool.t()} | {:error, ArchAstro.Error.reason()}

Update an agent tool

Updates the configuration of an existing tool. All parameters are optional; supply only the fields you want to change. Unspecified fields are left as-is.

You can update both "draft" and "active" tools. Updating an active tool takes effect on the next agent run; any run already in progress continues with the configuration it loaded at start.

Supplying template re-resolves the referenced AgentToolTemplate and patches the tool in place, preserving its status, lookup_key, kind, and agent association. Any other params you supply alongside template override the template defaults.

Requires app scope. The authenticated caller must own the tool's parent agent.

The updated tool.