--- title: "Create Tool" method: POST path: "/api/v1/tools/" tags: ["tools"] --- # Create Tool `POST /api/v1/tools/` Create a new tool ## Request body - ToolCreateRequest — Request model to create a tool. - `name` string, required — The name of the tool - `definition` ToolDefinition, required — A tool that can be called from an LLM during the conversation. See https://docs.syllable.ai/Resources/Tools. - `type` 'action' | 'endpoint' | 'context' | 'log', nullable — The action to take when the LLM calls the tool. - `tool` InternalTool, required — A tool definition to be used by the OpenAI API. - `type` 'function' — Always `function`. - `function` ToolFunction, required — A function available to an agent. See: - https://learn.microsoft.com/en-us/azure/ai-services/openai/how-to/function-calling - `name` string, required — The name of the function/tool call. - `description` string, required — The description of the tool. - `parameters` unknown, required - `endpoint` ToolHttpEndpoint — The configuration for an HTTP API call by a tool. - `url` string, required — The endpoint URL of the external service to call. - `method` 'get' | 'post' | 'put' | 'delete', required — The HTTP method to use for a tool HTTP request. - `argument_location` 'body' | 'form' | 'path' | 'query', required — The location of the argument in a tool HTTP request. 'body' is used for JSON data in the POST request body. 'form' is used for form data in the POST request body. 'path' is used for URL path parameters. 'query' is used for query parameters in the URL. - `timeout` number, nullable — Timeout in seconds for the HTTP request. Default 20 seconds when not set. - `context` Context - `task` union — Task implementation details - union - ExpressionTask - `id` string, nullable — A unique identifier for the task. - `config` object, nullable - `variables` Variable[], nullable - … - `metadata` ContextTaskMetadata - … - `tool` ContextToolInfo - … - `type` 'expression' - `version` 'v1alpha' - `inputs` InputParameter[] - … - `expression` union — Expression for task output/logic. Supported expression forms: (1) JMESPath string (default for plain strings), (2) typed JMESPath object {"type":"jp"|"jmespath","expression":"..."}, or (3) typed CEL object {"type":"cel","expression":"..."}. - … - `output` unknown - `on` ExpressionTaskEvents — Actions to perform when events occur (start, submit). - … - LoadToolFromFileTask — Bootstraps a tool from a file (for internal developer use only if ENV.local=True). - `id` string, nullable — A unique identifier for the task. - `config` object, nullable - `variables` Variable[], nullable - … - `metadata` ContextTaskMetadata - … - `tool` ContextToolInfo - … - `type` 'import' - `version` 'v1alpha' - `file` union, required — The local path of the tool definition JSON file. - … - EventTask - `id` string, nullable — A unique identifier for the task. - `config` object, nullable - `variables` Variable[], nullable - … - `metadata` ContextTaskMetadata - … - `tool` ContextToolInfo - … - `type` 'event' - `version` 'v1alpha' - `on` EventTaskEvents - … - StepsTask - `id` string, nullable — A unique identifier for the task. - `config` object, nullable - `variables` Variable[], nullable - … - `metadata` ContextTaskMetadata - … - `tool` ContextToolInfo - … - `type` 'steps' - `version` 'v1alpha' - `start` 'auto' | 'manual' — Controls when the workflow activation lifecycle runs. `auto` activates at session start; `manual` activates on first invocation. - `steps` Step[] - … - union[] - union - ExpressionTask - … - LoadToolFromFileTask — Bootstraps a tool from a file (for internal developer use only if ENV.local=True). - … - EventTask - … - StepsTask - … - `defaults` union — The default values for the parameters of the function/tool call. - unknown - object - `static_parameters` StaticToolParameter[], nullable — Parameters for the tool whose values should be set at config time (i.e., not provided by the LLM). - `name` string, required — The name of the parameter - must be unique within the tool. - `description` string, nullable — The description of the parameter. - `required` boolean, required — Whether the parameter is required to have a value assigned. - `type` 'string' | 'int' | 'boolean' | 'data_source_list', required — The expected type for a static tool parameter. - `default` string, nullable — The default value for the parameter. If `type` is string, must be a string. If `type` is int, must be an int. If `type` is boolean, must be a boolean. If `type` is data_source_list, must be a list of strings (data source names). - `result` unknown - `options` ToolOptions — The options for a tool call. - `propagate_tool_result` boolean — Whether the tool call result should be propagated to the caller. - `service_id` integer, required — Internal ID of the service to which the tool belongs ## Response `200` Successful Response - ToolResponse — Response model for tool operations. A tool is a function that an agent can call to perform actions like accessing databases, making API calls, or processing data. For an agent to have access to a tool, the prompt associated with that agent should be linked to the tool and include instructions to use it. For more information, see [Console docs](https://docs.syllable.ai/Resources/Tools). - `name` string, required — The name of the tool - `definition` ToolDefinition, required — A tool that can be called from an LLM during the conversation. See https://docs.syllable.ai/Resources/Tools. - `type` 'action' | 'endpoint' | 'context' | 'log', nullable — The action to take when the LLM calls the tool. - `tool` InternalTool, required — A tool definition to be used by the OpenAI API. - `type` 'function' — Always `function`. - `function` ToolFunction, required — A function available to an agent. See: - https://learn.microsoft.com/en-us/azure/ai-services/openai/how-to/function-calling - `name` string, required — The name of the function/tool call. - `description` string, required — The description of the tool. - `parameters` unknown, required - `endpoint` ToolHttpEndpoint — The configuration for an HTTP API call by a tool. - `url` string, required — The endpoint URL of the external service to call. - `method` 'get' | 'post' | 'put' | 'delete', required — The HTTP method to use for a tool HTTP request. - `argument_location` 'body' | 'form' | 'path' | 'query', required — The location of the argument in a tool HTTP request. 'body' is used for JSON data in the POST request body. 'form' is used for form data in the POST request body. 'path' is used for URL path parameters. 'query' is used for query parameters in the URL. - `timeout` number, nullable — Timeout in seconds for the HTTP request. Default 20 seconds when not set. - `context` Context - `task` union — Task implementation details - union - ExpressionTask - `id` string, nullable — A unique identifier for the task. - `config` object, nullable - `variables` Variable[], nullable - … - `metadata` ContextTaskMetadata - … - `tool` ContextToolInfo - … - `type` 'expression' - `version` 'v1alpha' - `inputs` InputParameter[] - … - `expression` union — Expression for task output/logic. Supported expression forms: (1) JMESPath string (default for plain strings), (2) typed JMESPath object {"type":"jp"|"jmespath","expression":"..."}, or (3) typed CEL object {"type":"cel","expression":"..."}. - … - `output` unknown - `on` ExpressionTaskEvents — Actions to perform when events occur (start, submit). - … - LoadToolFromFileTask — Bootstraps a tool from a file (for internal developer use only if ENV.local=True). - `id` string, nullable — A unique identifier for the task. - `config` object, nullable - `variables` Variable[], nullable - … - `metadata` ContextTaskMetadata - … - `tool` ContextToolInfo - … - `type` 'import' - `version` 'v1alpha' - `file` union, required — The local path of the tool definition JSON file. - … - EventTask - `id` string, nullable — A unique identifier for the task. - `config` object, nullable - `variables` Variable[], nullable - … - `metadata` ContextTaskMetadata - … - `tool` ContextToolInfo - … - `type` 'event' - `version` 'v1alpha' - `on` EventTaskEvents - … - StepsTask - `id` string, nullable — A unique identifier for the task. - `config` object, nullable - `variables` Variable[], nullable - … - `metadata` ContextTaskMetadata - … - `tool` ContextToolInfo - … - `type` 'steps' - `version` 'v1alpha' - `start` 'auto' | 'manual' — Controls when the workflow activation lifecycle runs. `auto` activates at session start; `manual` activates on first invocation. - `steps` Step[] - … - union[] - union - ExpressionTask - … - LoadToolFromFileTask — Bootstraps a tool from a file (for internal developer use only if ENV.local=True). - … - EventTask - … - StepsTask - … - `defaults` union — The default values for the parameters of the function/tool call. - unknown - object - `static_parameters` StaticToolParameter[], nullable — Parameters for the tool whose values should be set at config time (i.e., not provided by the LLM). - `name` string, required — The name of the parameter - must be unique within the tool. - `description` string, nullable — The description of the parameter. - `required` boolean, required — Whether the parameter is required to have a value assigned. - `type` 'string' | 'int' | 'boolean' | 'data_source_list', required — The expected type for a static tool parameter. - `default` string, nullable — The default value for the parameter. If `type` is string, must be a string. If `type` is int, must be an int. If `type` is boolean, must be a boolean. If `type` is data_source_list, must be a list of strings (data source names). - `result` unknown - `options` ToolOptions — The options for a tool call. - `propagate_tool_result` boolean — Whether the tool call result should be propagated to the caller. - `service_id` integer, required — Internal ID of the service to which the tool belongs - `id` integer, required — The internal ID of the tool - `last_updated_comments` string, nullable — Comments for the most recent edit to the tool. - `service_name` string, nullable — The name of the service to which the tool belongs - `prompts_info` ToolPromptInfo[], nullable — IDs and names of the prompts linked to the tool - `id` integer, required — The ID of the prompt - `name` string, required — The name of the prompt - `agents_info` ToolAgentInfo[], nullable — IDs and names of the agents linked to the tool via a prompt - `id` integer, required — The internal ID of the agent - `name` string, required — The name of the agent - `last_updated` string, date-time, required — The timestamp of the most recent update to the tool - `last_updated_by` string, required — The email of the user who last updated the tool - `version_number` integer, required — Highest tools_history snapshot version for this tool; the tools row defaults to 1. - `validation_issues` ValidationIssue[], nullable — Validation issues found in the tool definition. Warnings and infos are informational; errors block the save. - `id` string, required — Stable machine-readable identifier (kebab-case) - `severity` 'info' | 'warning' | 'error' - `message` string, required — Human-readable description - `path` string, nullable — JSONPath-style location (e.g. $.context.task.steps[2]) - `value` string, nullable — The offending value, when it adds clarity ## Other responses - `422` — Validation Error --- [API](https://skmtc.net/asksyllable/apis/syllablesdk.md) · [All operations](https://skmtc.net/asksyllable/apis/syllablesdk/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/asksyllable/syllablesdk/versions/ac3228f980bb/schema)