--- title: "Create an agent tool" method: POST path: "/api/v1/agents/{agent}/agent_tools" --- # Create an agent tool `POST /api/v1/agents/{agent}/agent_tools` Creates a new tool and attaches it to the specified agent. Tools can be either `"builtin"` (a platform-provided capability identified by `builtin_tool_key`) or `"custom"` (a caller-defined tool with its own name, description, parameter schema, and handler). New tools are created in `"draft"` status by default unless `status: "active"` is explicitly supplied. Draft tools are not exposed to the LLM during agent runs; call the activate endpoint to promote them. For built-in tools that support multiple instances per agent (those whose catalog entry has a `multi_instance_mode`), supply `name_prefix` to namespace the LLM-facing tool names. Requires app scope. ## Path parameters - `agent` string, required ## Request body - object - `async` boolean — When `true`, the tool executes asynchronously and the agent does not block waiting for a result. Applies to `"custom"` tools. - `builtin_tool_config` object — Configuration object for the built-in tool. Shape is defined by the catalog entry's `config_schema` for the chosen `builtin_tool_key`. Applies only to `"builtin"` tools. - `builtin_tool_key` string — Key identifying the built-in tool type to add (e.g. `"knowledge_search"`). Required when `kind` is `"builtin"`. Must match a key in the tool catalog. - `config` string — Config ID (`cfg_...`) referencing the script or workflow graph that implements the tool handler. Applies to `"custom"` tools. - `description` string — Human-readable description of what the tool does. Shown to the LLM as context. Applies primarily to `"custom"` tools. - `handler_type` string — Execution handler for the tool. One of `"script"` or `"workflow_graph"`. Applies to `"custom"` tools. - `kind` string, required — Tool kind. One of `"builtin"` or `"custom"`. - `lookup_key` string — Optional stable identifier you can use to look up this tool without its ID. Must be unique within the app. Useful for idempotent provisioning. - `metadata` object — Arbitrary key-value metadata to attach to the tool. Not interpreted by the platform. - `name` string — Display name for the tool. Required when `kind` is `"custom"`. - `name_prefix` string — Per-instance namespace for built-in tools that support multiple instances per agent. Stamped onto LLM-facing tool names (e.g. `"org"` produces `"org_knowledge_search"`). Must match `^[a-z][a-z0-9_]*$` and be at most 24 characters. Required for `"namespaced"` multi-instance tools; omit for single-instance tools. - `parameters` object — JSON Schema object describing the tool's input parameters. Used by the LLM to construct valid tool calls. Applies to `"custom"` tools. - `status` string — Initial status of the tool. One of `"draft"` or `"active"`. Defaults to `"draft"` when omitted. ## Response `200` Successful response - AgentTool — A tool attached to an agent, defining a capability the agent can invoke during a conversation or task run. - `agent` string — ID of the agent this tool belongs to (`agi_...`). - `app` string — ID of the application that owns this tool (`dap_...`). - `async` boolean — `true` when the tool executes asynchronously and returns a task handle rather than an immediate result. - `builtin_tool_config` object — Provider-specific configuration for the built-in tool. Present only when `kind` is `"builtin"`. Shape varies by `builtin_tool_key`. - `builtin_tool_key` string — Registry key identifying the built-in tool implementation. Present only when `kind` is `"builtin"`. - `config` string — ID of the config record (`cfg_...`) containing this tool's full configuration. `null` for inline-only tools. - `created_at` string, date-time — When the tool was created (ISO 8601). - `description` string — Description of what the tool does, passed to the LLM as part of the tool definition. Resolved from the built-in registry for `kind: "builtin"` tools. - `handler_type` string — Execution handler type. One of `"http"`, `"script"`, or `"builtin"`. - `id` string, required — Tool ID (`atl_...`). - `instruction` string — Optional system-level instruction appended to the agent prompt when this tool is active. - `kind` string — Tool kind. One of `"builtin"`, `"custom"`, or `"mcp"`. - `last_applied_template_config` string — ID of the AgentToolTemplate config (`cfg_...`) this tool was last provisioned or updated from. `null` for manually created tools. - `lookup_key` string — Stable, user-defined identifier for this tool within the agent. Unique per agent. - `metadata` object — Arbitrary key-value metadata attached to the tool. Not interpreted by the platform. - `name` string — Human-readable name of the tool as exposed to the LLM. Resolved from the built-in registry for `kind: "builtin"` tools. - `name_prefix` string — Per-instance namespace prepended to LLM-facing tool names for built-in tools that support multiple instances per agent. `null` when not applicable. - `parameters` object — JSON Schema object describing the tool's input parameters as presented to the LLM. - `parameters_config` string — ID of the config record (`cfg_...`) storing the tool's parameter schema. `null` when parameters are defined inline. - `status` string — Current status of the tool. One of `"active"` or `"disabled"`. - `updated_at` string, date-time — When the tool was last modified (ISO 8601). ## Other responses - `401` — Unauthorized - `403` — Forbidden - app scope required - `404` — Agent not found - `422` — Validation failed --- [API](https://skmtc.net/archastro/apis/archastro-platform-api.md) · [All operations](https://skmtc.net/archastro/apis/archastro-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/archastro/archastro-platform-api/versions/a8772b442f86/schema)