> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agents.labs.bandwidth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a reusable tool

> MCP reference for create_tool.

Tool: `create_tool`. Requires **Editor, Admin, or Owner** in the applicable workspace and a connected [OAuth session](https://docs.agents.labs.bandwidth.com/mcp/authentication.md).

Creates an HTTP API, end-call, transfer-call, calculator, or MCP tool from the typed `request`. Use an existing `credential_uuid` from `list_credentials` for authentication; create secrets in the console. Tools with stored credentials, headers, or preset values additionally require Admin or Owner. MCP creation can discover the remote server’s catalog.

Inspect `created`, `tool_uuid`, and failure fields. Possible errors include `validation_error`, `credential_not_found`, `credential_admin_required`, and `placeholder_not_allowed`. A created tool is not automatically attached to an agent; reference its UUID in the agent definition.

Integration-managed tool groups cannot be created with this tool. Do not set `integration_provider` or `integration_id`: the request returns `managed_integration_tool`. For Calendly, use the [connection endpoints](https://docs.agents.labs.bandwidth.com/api-reference/calendly/status.md) and then select the discovered tools for each agent.

## Arguments

| Name | Type | Required | Defaults and limits |
| - | - | - | - |
| `request` | object | Yes | See full schema |

## Example arguments

Replace sample resource IDs with IDs returned in your selected workspace.

```json theme={null}
{
  "request": {
    "name": "Lookup order",
    "category": "http_api",
    "definition": {
      "type": "http_api",
      "config": {
        "method": "GET",
        "url": "https://api.example.com/orders"
      }
    }
  }
}
```

## Result and errors

The schema below describes MCP `structuredContent`, including the `result` wrapper where present. Your client may also display a text representation. Read success flags and structured errors before continuing; transport success alone does not prove the operation succeeded. Authentication, missing membership, and insufficient role can fail before a tool result is produced. See [troubleshooting](https://docs.agents.labs.bandwidth.com/mcp/troubleshooting.md).

**Effect:** Changes state. **Retry:** Do not blindly repeat successful calls. Discovery annotations describe behavior; they do not grant permission or replace confirmation for consequential actions.

> [accordion] Input schema
>
> ```json theme={null}
> {
>   "additionalProperties": false,
>   "properties": {
>     "request": {
>       "properties": {
>         "category": {
>           "default": "http_api",
>           "enum": [
>             "http_api",
>             "end_call",
>             "transfer_call",
>             "calculator",
>             "native",
>             "integration",
>             "mcp"
>           ],
>           "type": "string"
>         },
>         "definition": {
>           "oneOf": [
>             {
>               "properties": {
>                 "config": {
>                   "properties": {
>                     "credential_uuid": {
>                       "anyOf": [
>                         {
>                           "type": "string"
>                         },
>                         {
>                           "type": "null"
>                         }
>                       ],
>                       "default": null
>                     },
>                     "customMessage": {
>                       "anyOf": [
>                         {
>                           "type": "string"
>                         },
>                         {
>                           "type": "null"
>                         }
>                       ],
>                       "default": null
>                     },
>                     "customMessageRecordingId": {
>                       "anyOf": [
>                         {
>                           "type": "string"
>                         },
>                         {
>                           "type": "null"
>                         }
>                       ],
>                       "default": null
>                     },
>                     "customMessageType": {
>                       "anyOf": [
>                         {
>                           "enum": [
>                             "text",
>                             "audio"
>                           ],
>                           "type": "string"
>                         },
>                         {
>                           "type": "null"
>                         }
>                       ],
>                       "default": null
>                     },
>                     "headers": {
>                       "anyOf": [
>                         {
>                           "additionalProperties": {
>                             "type": "string"
>                           },
>                           "type": "object"
>                         },
>                         {
>                           "type": "null"
>                         }
>                       ],
>                       "default": null
>                     },
>                     "method": {
>                       "enum": [
>                         "GET",
>                         "POST",
>                         "PUT",
>                         "PATCH",
>                         "DELETE"
>                       ],
>                       "type": "string"
>                     },
>                     "parameters": {
>                       "anyOf": [
>                         {
>                           "items": {
>                             "properties": {
>                               "description": {
>                                 "type": "string"
>                               },
>                               "name": {
>                                 "type": "string"
>                               },
>                               "required": {
>                                 "default": true,
>                                 "type": "boolean"
>                               },
>                               "type": {
>                                 "enum": [
>                                   "string",
>                                   "number",
>                                   "boolean",
>                                   "object",
>                                   "array"
>                                 ],
>                                 "type": "string"
>                               }
>                             },
>                             "required": [
>                               "name",
>                               "type",
>                               "description"
>                             ],
>                             "type": "object"
>                           },
>                           "type": "array"
>                         },
>                         {
>                           "type": "null"
>                         }
>                       ],
>                       "default": null
>                     },
>                     "preset_parameters": {
>                       "anyOf": [
>                         {
>                           "items": {
>                             "properties": {
>                               "name": {
>                                 "type": "string"
>                               },
>                               "required": {
>                                 "default": true,
>                                 "type": "boolean"
>                               },
>                               "type": {
>                                 "enum": [
>                                   "string",
>                                   "number",
>                                   "boolean",
>                                   "object",
>                                   "array"
>                                 ],
>                                 "type": "string"
>                               },
>                               "value_template": {
>                                 "type": "string"
>                               }
>                             },
>                             "required": [
>                               "name",
>                               "type",
>                               "value_template"
>                             ],
>                             "type": "object"
>                           },
>                           "type": "array"
>                         },
>                         {
>                           "type": "null"
>                         }
>                       ],
>                       "default": null
>                     },
>                     "timeout_ms": {
>                       "anyOf": [
>                         {
>                           "minimum": 1,
>                           "type": "integer"
>                         },
>                         {
>                           "type": "null"
>                         }
>                       ],
>                       "default": 5000
>                     },
>                     "url": {
>                       "type": "string"
>                     }
>                   },
>                   "required": [
>                     "method",
>                     "url"
>                   ],
>                   "type": "object"
>                 },
>                 "schema_version": {
>                   "default": 1,
>                   "type": "integer"
>                 },
>                 "type": {
>                   "const": "http_api",
>                   "type": "string"
>                 }
>               },
>               "required": [
>                 "type",
>                 "config"
>               ],
>               "type": "object"
>             },
>             {
>               "properties": {
>                 "config": {
>                   "properties": {
>                     "audioRecordingId": {
>                       "anyOf": [
>                         {
>                           "type": "string"
>                         },
>                         {
>                           "type": "null"
>                         }
>                       ],
>                       "default": null
>                     },
>                     "customMessage": {
>                       "anyOf": [
>                         {
>                           "type": "string"
>                         },
>                         {
>                           "type": "null"
>                         }
>                       ],
>                       "default": null
>                     },
>                     "endCallReason": {
>                       "default": false,
>                       "type": "boolean"
>                     },
>                     "endCallReasonDescription": {
>                       "anyOf": [
>                         {
>                           "type": "string"
>                         },
>                         {
>                           "type": "null"
>                         }
>                       ],
>                       "default": null
>                     },
>                     "messageType": {
>                       "default": "none",
>                       "enum": [
>                         "none",
>                         "custom",
>                         "audio"
>                       ],
>                       "type": "string"
>                     }
>                   },
>                   "type": "object"
>                 },
>                 "schema_version": {
>                   "default": 1,
>                   "type": "integer"
>                 },
>                 "type": {
>                   "const": "end_call",
>                   "type": "string"
>                 }
>               },
>               "required": [
>                 "type",
>                 "config"
>               ],
>               "type": "object"
>             },
>             {
>               "properties": {
>                 "config": {
>                   "properties": {
>                     "audioRecordingId": {
>                       "anyOf": [
>                         {
>                           "type": "string"
>                         },
>                         {
>                           "type": "null"
>                         }
>                       ],
>                       "default": null
>                     },
>                     "customMessage": {
>                       "anyOf": [
>                         {
>                           "type": "string"
>                         },
>                         {
>                           "type": "null"
>                         }
>                       ],
>                       "default": null
>                     },
>                     "destination": {
>                       "type": "string"
>                     },
>                     "messageType": {
>                       "default": "none",
>                       "enum": [
>                         "none",
>                         "custom",
>                         "audio"
>                       ],
>                       "type": "string"
>                     },
>                     "timeout": {
>                       "default": 30,
>                       "maximum": 120,
>                       "minimum": 5,
>                       "type": "integer"
>                     }
>                   },
>                   "required": [
>                     "destination"
>                   ],
>                   "type": "object"
>                 },
>                 "schema_version": {
>                   "default": 1,
>                   "type": "integer"
>                 },
>                 "type": {
>                   "const": "transfer_call",
>                   "type": "string"
>                 }
>               },
>               "required": [
>                 "type",
>                 "config"
>               ],
>               "type": "object"
>             },
>             {
>               "properties": {
>                 "schema_version": {
>                   "default": 1,
>                   "type": "integer"
>                 },
>                 "type": {
>                   "const": "calculator",
>                   "type": "string"
>                 }
>               },
>               "required": [
>                 "type"
>               ],
>               "type": "object"
>             },
>             {
>               "properties": {
>                 "config": {
>                   "properties": {
>                     "account_name": {
>                       "anyOf": [
>                         {
>                           "type": "string"
>                         },
>                         {
>                           "type": "null"
>                         }
>                       ],
>                       "default": null
>                     },
>                     "credential_uuid": {
>                       "anyOf": [
>                         {
>                           "type": "string"
>                         },
>                         {
>                           "type": "null"
>                         }
>                       ],
>                       "default": null
>                     },
>                     "discovered_tools": {
>                       "items": {
>                         "additionalProperties": true,
>                         "type": "object"
>                       },
>                       "type": "array"
>                     },
>                     "integration_id": {
>                       "anyOf": [
>                         {
>                           "type": "string"
>                         },
>                         {
>                           "type": "null"
>                         }
>                       ],
>                       "default": null
>                     },
>                     "integration_provider": {
>                       "anyOf": [
>                         {
>                           "type": "string"
>                         },
>                         {
>                           "type": "null"
>                         }
>                       ],
>                       "default": null
>                     },
>                     "sse_read_timeout_secs": {
>                       "default": 300,
>                       "minimum": 0,
>                       "type": "integer"
>                     },
>                     "timeout_secs": {
>                       "default": 30,
>                       "minimum": 0,
>                       "type": "integer"
>                     },
>                     "tools_filter": {
>                       "items": {
>                         "type": "string"
>                       },
>                       "type": "array"
>                     },
>                     "transport": {
>                       "const": "streamable_http",
>                       "default": "streamable_http",
>                       "type": "string"
>                     },
>                     "url": {
>                       "type": "string"
>                     }
>                   },
>                   "required": [
>                     "url"
>                   ],
>                   "type": "object"
>                 },
>                 "schema_version": {
>                   "default": 1,
>                   "type": "integer"
>                 },
>                 "type": {
>                   "const": "mcp",
>                   "type": "string"
>                 }
>               },
>               "required": [
>                 "type",
>                 "config"
>               ],
>               "type": "object"
>             }
>           ]
>         },
>         "description": {
>           "anyOf": [
>             {
>               "type": "string"
>             },
>             {
>               "type": "null"
>             }
>           ],
>           "default": null
>         },
>         "icon": {
>           "anyOf": [
>             {
>               "maxLength": 50,
>               "type": "string"
>             },
>             {
>               "type": "null"
>             }
>           ],
>           "default": "globe"
>         },
>         "icon_color": {
>           "anyOf": [
>             {
>               "maxLength": 7,
>               "type": "string"
>             },
>             {
>               "type": "null"
>             }
>           ],
>           "default": "#3B82F6"
>         },
>         "name": {
>           "maxLength": 255,
>           "type": "string"
>         }
>       },
>       "required": [
>         "name",
>         "definition"
>       ],
>       "type": "object"
>     }
>   },
>   "required": [
>     "request"
>   ],
>   "type": "object"
> }
> ```

> [accordion] Result schema
>
> ```json theme={null}
> {
>   "properties": {
>     "result": {
>       "anyOf": [
>         {
>           "properties": {
>             "category": {
>               "type": "string"
>             },
>             "created": {
>               "const": true,
>               "type": "boolean"
>             },
>             "definition": {
>               "additionalProperties": true,
>               "type": "object"
>             },
>             "name": {
>               "type": "string"
>             },
>             "status": {
>               "enum": [
>                 "active",
>                 "archived",
>                 "draft"
>               ],
>               "type": "string"
>             },
>             "tool_uuid": {
>               "type": "string"
>             }
>           },
>           "required": [
>             "created",
>             "tool_uuid",
>             "name",
>             "category",
>             "status",
>             "definition"
>           ],
>           "type": "object"
>         },
>         {
>           "properties": {
>             "created": {
>               "const": false,
>               "type": "boolean"
>             },
>             "error": {
>               "type": "string"
>             },
>             "error_code": {
>               "type": "string"
>             }
>           },
>           "required": [
>             "created",
>             "error_code",
>             "error"
>           ],
>           "type": "object"
>         }
>       ]
>     }
>   },
>   "required": [
>     "result"
>   ],
>   "type": "object"
> }
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.