--- title: "Remove Agent Tool" method: DELETE path: "/v1/agents/{agent_id}/tools/{tool_id}" tags: ["API v1", "Agents", "Agent Tools"] --- # Remove Agent Tool `DELETE /v1/agents/{agent_id}/tools/{tool_id}` ## Request - Base URL: `https://api.xpander.ai` (the document declares no server; this is the origin it was published from) - URL: `https://api.xpander.ai/v1/agents/{agent_id}/tools/{tool_id}` - Auth: API key in header `x-api-key` Remove a tool from an agent by its tool id (the `id` from list agent tools). ## Path parameters - `agent_id` string, required - `tool_id` string, required ## Query parameters - `deploy` boolean: Deploy the agent after removing so the change takes effect immediately. ## Response `200` Successful Response - AgentTool[] - `id` string, required: Stable handle for this attached tool. Pass it to DELETE to remove the tool. - `type` 'action' | 'custom_function' | 'mcp' | 'agent' | 'workflow' | 'skill', required: Type of a tool attached to an agent. - `name` string, nullable: Human-readable tool name. - `connection_id` string, nullable: Connector connection id. Actions only. - `operation_id` string, nullable: Operation catalog id. Actions only. - `operation_name` string, nullable: OpenAPI operationId. Actions only. - `use_mock` boolean, nullable: Operation serves AI-generated mock data instead of the real API. Actions only. - `connector_auth_mode` string, nullable: Binding auth mode: 'autonomous' (connection credential) or 'user_authentication' (each caller signs in). Actions only. - `connector_share_user_token` boolean, nullable: Whether a user's authorized connector token is shared across the org's other agents. Actions only. - `connector_write_mode` string, nullable: What happens to a call that changes something: 'allow', 'ask' (a person approves it first) or 'block'. Actions only; None means allow. - `requires_approval` boolean, nullable: Whether a person must approve this action before it runs. Actions only; None means never configured. - `approval_rule` object, nullable: The stored approval rule for this action (approvers, channels, allowed scopes, on_deny), so a settings UI opens on real values. Never carries arguments or credentials. - `custom_function_id` string, nullable: Custom function id. Custom functions only. - `mcp_id` string, nullable: MCP registry id. MCP only. - `allowed_tools` string[], nullable: Subset of MCP tools exposed. MCP only. - `mcp_url` string, nullable: MCP server url. MCP only. - `mcp_type` string, nullable: MCP server type: remote (url) or local (command, hosted in the agent's workspace). MCP only. - `mcp_command` string, nullable: Command that starts a local MCP server. Local MCP only. - `mcp_env_vars` object, nullable: Environment of a local MCP server. A ${NAME} reference to a workspace secret is returned as written; a literal value is returned blank, the same way header values are. Local MCP only. - `mcp_auth_type` string, nullable: MCP auth type (api_key/oauth2/custom_headers/sso_user/none). MCP only. - `mcp_registry_id` string, nullable: Registry entry id when this MCP is attached from the shared org registry (editing it affects every agent). Absent for inline MCPs. MCP only. - `mcp_transport` string, nullable: MCP transport (streamable-http/sse/stdio). MCP only. - `mcp_registry_name` string, nullable: Name of the bound registry entry, read for every viewer, also when the entry is another member's personal one. Set by the agent tools list (GET /v1/agents/{id}/tools), not by the agent views. MCP only. - `mcp_registry_access_scope` string, nullable: Audience of the bound registry entry: personal or organizational. MCP only. - `mcp_registry_owner_name` string, nullable: Display name of the member who owns a personal registry entry. MCP only. - `mcp_headers` string[], nullable: Custom header names configured on the MCP (keys only; values are never returned). MCP only. - `mcp_client_id` string, nullable: OAuth2 client id for the MCP, if set. MCP only. - `mcp_additional_scopes` string[], nullable: Extra OAuth2 scopes for the MCP. MCP only. - `mcp_share_user_token` boolean, nullable: Whether the authorized MCP token is shared across the org's other agents. MCP only. - `mcp_share_connection` boolean, nullable: Whether a caller with no sign-in of their own runs this agent's OAuth MCP on the owner's connection. MCP only. - `mcp_sso_token` string, nullable: For mcp_auth_type sso_user: access, id or exchange. MCP only. - `mcp_sso_audience` string, nullable: For mcp_auth_type sso_user with exchange: the audience. MCP only. - `mcp_has_api_key` boolean, nullable: Whether an API key is stored for the MCP (the value is never returned). MCP only. - `mcp_has_client_secret` boolean, nullable: Whether an OAuth2 client secret is stored for the MCP (the value is never returned). MCP only. - `mcp_connection_status` string, nullable: Last probe outcome for the MCP: connected / tools_failing / auth_required / error. MCP only. - `mcp_tools_verified` boolean, nullable: True when the last probe's health-check tool call succeeded, so the tools are known to run. MCP only. - `mcp_last_error` string, nullable: Why the last probe did not report connected. MCP only. - `mcp_health_check_tool` string, nullable: The tool the health probe calls to prove calls work. MCP only. - `mcp_health_check_error_text` string, nullable: Text that marks a failed health-check answer. MCP only. - `mcp_tools_count` integer, nullable: Tool count discovered by the last probe. MCP only. - `mcp_last_checked_at` string, nullable: ISO timestamp of the last probe. MCP only. - `target_id` string, nullable: Referenced sub-agent or workflow id. - `skill_name` string, nullable: Skill name from the xpander skills catalog. Skills only. - `visible` boolean: False when the tool is authored hidden and must not be listed in the app; it stays attached and keeps running. ## Other responses - `422`: Validation Error --- [API](https://skmtc.dev/xpander/apis/xpander-ai-api-service.md) - [All operations](https://skmtc.dev/xpander/apis/xpander-ai-api-service/llms.txt) - [OpenAPI document](https://skmtc.dev/xpander/apis/xpander-ai-api-service/revisions/4389ec0875d0?raw)