> ## Documentation Index > Fetch the complete documentation index at: https://docs.prisme.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update a tool attached to an agent > Shallow-merges the body into the entry (matched by `id`, or by `name` when it has none). `id`, `type`, `catalog_id`, `auth` and `icon_url` are ignored: they stay as attached. The resulting `tools[]` is checked like `PATCH /v1/agents/{agentId}` (tool names, `tool_filter` shape, knowledge base access). When the agent is published, `has_draft_changes` is set to `true`. Returns the updated entry. ## OpenAPI ````yaml /api-reference/agent-factory/swagger.yml patch /v1/agents/{agentId}/tools/{toolId} openapi: 3.0.3 info: version: 1.0.0 title: Agent Factory API description: | Public REST API for the Agent Factory workspace - agents, conversations, messages, tools, artifacts, sharing, ratings, and discovery. Powered by Prisme.ai's runtime; all endpoints are exposed under each workspace's webhook namespace. contact: name: Prisme.ai url: https://prisme.ai servers: - url: https://{host}/v2/workspaces/slug:agent-factory/webhooks description: Prisme.ai workspace webhooks variables: host: default: api.studio.prisme.ai description: API host (override for self-hosted or sandbox) security: - BearerAuth: [] - OrgApiKeyAuth: [] tags: - name: Agents description: Agent CRUD, discovery, AGENTS.md import/export. - name: Access description: Agent access bindings, sharing, and access requests. - name: ApiKeys description: Agent-scoped API key management (mint, revoke, rotate). - name: Publishing description: Publish or discard draft changes on an agent. - name: Ratings description: User ratings on published agents. - name: Profiles description: >- Agent profiles/presets catalog (simple, workflow, agent_light, agent_full, orchestrator). - name: Activity description: Activity feed for agents (events, errors, lifecycle changes). - name: Analytics description: Agent usage analytics (series + summary). - name: Conversations description: Conversations on an agent (CRUD, archive, star). - name: Messages description: Send messages to an agent (synchronous send + SSE stream). - name: Tasks description: Async task lifecycle (list, fetch, cancel, resolve, subscribe). - name: Artifacts description: Generated artifacts (files, code, content) attached to a task. - name: Shares description: Conversation, message, and artifact share-link snapshots. - name: A2A description: Agent-to-agent JSON-RPC 2.0 gateway (well-known agent.json + RPC). - name: Tools description: Per-agent tool catalogue (system tools, MCP servers, function tools). - name: Retention description: Per-agent and org-wide conversation retention policies. - name: Traces description: >- Execution traces of agent turns (editor debugging, `agent-factory:traces:read`). - name: Evaluations description: Agent evaluation runs and results. - name: Push description: Mobile device registration for push notifications. - name: Voice description: Voice sessions with an agent (native voice relay). - name: Admin description: | GDPR operations called by the AI Insights admin screens. They require elevated permissions: the caller must be a platform administrator (`platformRole` `superadmin` or `root`). The export route also lets a user export their own data. Each route is rate limited to 10 calls per hour per caller. paths: /v1/agents/{agentId}/tools/{toolId}: patch: tags: - Tools summary: Update a tool attached to an agent description: | Shallow-merges the body into the entry (matched by `id`, or by `name` when it has none). `id`, `type`, `catalog_id`, `auth` and `icon_url` are ignored: they stay as attached. The resulting `tools[]` is checked like `PATCH /v1/agents/{agentId}` (tool names, `tool_filter` shape, knowledge base access). When the agent is published, `has_draft_changes` is set to `true`. Returns the updated entry. operationId: updateAgentTool parameters: - name: agentId in: path required: true schema: type: string maxLength: 64 - name: toolId in: path required: true schema: type: string maxLength: 128 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ToolPatchInput' responses: '200': description: Updated tool entry. content: application/json: schema: $ref: '#/components/schemas/Tool' '400': description: Invalid tool name or `tool_filter` (`VALIDATION_ERROR`). content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Authentication required. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: >- Forbidden, or a knowledge base the caller cannot read / from another organization. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Tool not found. content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- The new `name` is already used by another entry of the agent (`DUPLICATE_NAME`). content: application/json: schema: $ref: '#/components/schemas/Error' '502': description: >- The knowledge base check could not reach storage (`KNOWLEDGE_BASE_CHECK_FAILED`). content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: ToolPatchInput: type: object description: > Fields to merge into a tool entry. `id`, `type`, `catalog_id`, `auth` and `icon_url` are ignored if sent. `null` clears a field (`name` excepted). properties: name: type: string maxLength: 128 pattern: ^[a-zA-Z0-9_-]+$ display_name: type: string nullable: true maxLength: 256 description: type: string nullable: true maxLength: 4096 vector_store_id: type: string nullable: true maxLength: 128 description: >- `file_search` only. A knowledge base the caller can read, in the agent's organization (403 otherwise). max_num_results: type: number nullable: true server: type: string nullable: true maxLength: 2048 headers: type: object nullable: true additionalProperties: true scope: type: string nullable: true maxLength: 256 allowSelfSignedCert: type: boolean nullable: true url: type: string nullable: true maxLength: 2048 parameters: type: object nullable: true additionalProperties: true tool_filter: $ref: '#/components/schemas/ToolFilter' Tool: type: object description: | Tool entry attached to an agent. Discriminated by `type` - `file_search` (requires `vector_store_id`), `mcp` (uses `server`, `headers`, `scope`), or `function` (uses `url`, `parameters`, `headers`). additionalProperties: true properties: id: type: string type: type: string enum: - file_search - mcp - function name: type: string pattern: ^[a-zA-Z0-9_-]+$ display_name: type: string description: type: string catalog_id: type: string description: >- Capabilities catalog entry the tool was added from. Fixed once the tool is attached - a tools array sent back through `PATCH /v1/agents/{agentId}` keeps the stored value - because the organization ceiling of an `mcp` entry is read through it. An `mcp` entry without one (a custom server) has no organization ceiling. auth: type: object additionalProperties: true icon_url: type: string vector_store_id: type: string description: Required for `file_search`. server: type: string description: MCP server URL (for `mcp`). headers: type: object additionalProperties: true scope: type: string url: type: string description: Required for `function`. parameters: type: object additionalProperties: true description: JSON Schema describing the function tool's parameters. tool_filter: $ref: '#/components/schemas/ToolFilter' Error: type: object required: - error - message properties: error: type: string description: >- Stable PascalCase or SNAKE_CASE error code (e.g. AgentNotFound, VALIDATION_ERROR, FORBIDDEN, METHOD_NOT_ALLOWED). message: type: string description: Human-readable error message. details: type: object description: Optional structured context for the error. additionalProperties: true ToolFilter: type: object nullable: true description: | MCP tool selection (`mcp` entries). Names are the server's own tool names (`tools/list` `name`), never the `__` canonical name. `allow`: only the listed tools are exposed, tools the server adds later stay hidden. `deny`: the listed tools are hidden, the others are exposed. Absent or `null`: every tool is exposed. An organization ceiling (the same shape on the capabilities catalog entry) applies on top; a tool must pass both. On any other tool type it is refused (400), except by `POST /v1/agents/{agentId}/tools`, which ignores it. required: - mode - tools properties: mode: type: string enum: - allow - deny tools: type: array items: type: string minLength: 1 securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: | User-bound credential carrying an identity: either a session JWT or a user access token (`at:*`) generated from the user settings UI. Send as `Authorization: Bearer `. Org API keys (`iak_*`) are **not** accepted here - they carry no user identity. Use the `x-prismeai-api-key` header instead (see `OrgApiKeyAuth`). OrgApiKeyAuth: type: apiKey in: header name: x-prismeai-api-key description: | Organization API key (`iak_{orgSlug}_{uuid}`). Unlike `Authorization: Bearer`, this credential is **not** tied to a user identity - it is bound to the org and its effective access is defined by the scopes / permission rules attached to it (it can be restricted to a single project, or kept broader). For Agent Factory, these keys can be generated directly from the Agent Factory UI (in addition to the AI Governance settings). Send as `x-prismeai-api-key: iak_...`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.