--- title: Create custom tools slug: agent-platform/docs/create-custom-tools docTags: createdAt: 2026-08-12T15:37:12.000Z --- While Agent Platform includes a powerful set of [system tools](docId\:ZExsvHuX-MENKqR8_eAvw), every business has unique needs, proprietary systems, and specific workflows that generic solutions cannot fully address. Custom tools let you extend Mark to help with your organization's specific use cases and needs. ## How custom tools work Before you start building custom tools, you should understand the fundamental concepts of how Mark discovers, manages, and interacts with custom tools. The following concepts form the foundation of the tool integration. ### Tool manifest The tool manifest is a structured declaration (often a JSON object) that describes your tool to Mark. Think of it like a blueprint or a resume for your tool. It tells Mark what your tool does and how to use it. The tool manifest includes the following: - **Name and description** – Human-readable label and summary of your tool. - **Parameters** – The inputs your tool expects, including name, data type (string, number, boolean, array, or object), description, and whether they are required. - **Execution details** – Information about the HTTP endpoint (URL) and method (GET or POST) Mark uses to execute your tool. - **Authentication requirements** – Details about any authentication needed to access your tool. If you use a [Mark tool creation SDK](docId\:Hd3sW1p_TUA5w1dWF8ID9), much of the manifest creation is automated. Understanding the manifest is still helpful for debugging or ensuring that Mark can correctly discover and execute your tool. ### Discovery endpoints The discovery endpoint is a specific HTTP endpoint (commonly `/discovery`) that returns your tool manifest and is exposed by your tool service. When you register a custom tool, Mark calls this endpoint to dynamically discover the tools your service provides. If this endpoint is inaccessible, returns errors, or provides a malformed manifest, Mark is not able to find or use your tools. The [Mark tool creation SDKs](docId\:Hd3sW1p_TUA5w1dWF8ID9) automate the creation and management of this endpoint. ### Tool execution After discovery, Mark can run your tool by sending a request to its execution endpoint. Typically, this is a POST request with a JSON body containing the input parameters. Your tool processes the request, performs the task, and sends back a response, usually as JSON. Understanding this request and response flow is key to building reliable tools. This is the actual "work" phase. Understanding the request and response format is crucial for implementing your tool's core logic. ### Authentication Authentication verifies that the request to your tool is coming from a trusted source. This protects your data and systems from unauthorized access. :::hint{type="info"} **Note** Mark supports only [Opti ID](docId\:pbehd96P529DqHZ0HOQlm) for tool authentication. Optimizely is working on releasing support for additional providers. ::: Common methods include the following: - **Bearer Tokens** – Mark sends a secret token in the `Authorization` header (for example, `Bearer YOUR_SECRET_TOKEN`), and your tool validates it. - **OAuth flows** – This is used for integrations with third-party services (for example, Google or Salesforce), where Mark must access user-specific data securely. Proper authentication ensures that only authorized requests can trigger your tools, protecting your data and systems. The [Mark tool creation SDKs](docId\:Hd3sW1p_TUA5w1dWF8ID9) provide helpers to simplify the implementation of these security measures. ### Configuration Tools often require environment variables, API keys, or database connection strings to run correctly in different environments like development, staging, and production. Avoid hardcoding sensitive information. Use configuration management so you can deploy the same tool across environments safely and securely. ## Mark tool creation SDKs Optimizely provides SDKs for popular programming languages, making it easier to build custom tools. Each SDK manages discovery, execution, and communication with Mark's tool management service. ### JavaScript (TypeScript) SDK - **Installation** – Install with [npm](https://www.npmjs.com). For example, ```bash npm install @optimizely-opal/opal-tools-sdk ``` :::Paragraph{listStyleType="disc" indent="2"} For installation and usage guidelines, see [https://www.npmjs.com/package/@optimizely-opal/opal-tools-sdk](https://www.npmjs.com/package/@optimizely-opal/opal-tools-sdk). ::: - **Best for** – Web-based tools, UI extensions, and Node.js or browser-based workflows. Great for high-concurrency network operations. - **Key features** - Type definitions for strong typing and better developer experience. - Express.js middleware for handling discovery and execution endpoints. - Decorators like `@tool()` for clean, readable tool definitions. - Built-in parameter validation. - Authentication helpers. ### Python SDK - **Installation** – Install with [pip](https://pypi.org/project/pip/). For example, ```bash pip install optimizely-opal.opal-tools-sdk ``` :::hint{type="info" indent="2"} **Note** The package name you install with pip is different from the module name you import in Python. Install with `pip install optimizely-opal.opal-tools-sdk`, but import with `import opal_tools_sdk`. ::: :::Paragraph{listStyleType="disc" indent="2"} For installation and usage guidelines, see [https://pypi.org/project/optimizely-opal.opal-tools-sdk/](https://pypi.org/project/optimizely-opal.opal-tools-sdk/). ::: - **Best for** – Backend automation, data processing, machine learning, and analytical tasks. - **Key features** - Decorators like `@tool()` to define tools. - Automatic creation of the `/discovery` endpoint. - Built-in parameter validation with Python type hints. - FastAPI integration for building APIs with Python 3.7+. - Authentication helpers. ### C# SDK - **Installation** – Install with [NuGet](https://www.nuget.org). For example, ```bash Install-Package OptimizelyOpal.OpalToolsSDK ``` :::Paragraph{listStyleType="disc" indent="2"} For installation and usage guidelines, see [https://www.nuget.org/packages/Optimizely.Opal.Tools/](https://www.nuget.org/packages/Optimizely.Opal.Tools/). ::: - **Best for** – Integrating with existing .NET applications and enterprise systems, especially in Microsoft-focused organizations. - **Key features** - C# attributes like `[Tool]` and `[RequiresAuth]` for defining tools. - ASP.NET Core integration for APIs and services. - Advanced parameter validation. - Built-in dependency injection support. ## How to choose an SDK Consider the following when deciding which SDK to use: - **Team expertise and tech stack** – Prefer the SDK your team already knows to reduce ramp-up time and simplify maintenance. - **Performance needs** – Match the language to the workload. - **C#** – Choose for high-performance, low-latency backend services. - **Python** – Choose for data-heavy processing, machine learning, and analytics. - **JavaScript** – Choose for I/O-bound work like concurrent web or API requests. - **Tool type** – Align the SDK with what the tool primarily does. - **Backend automation or workflows** – Use C# or Python. - **Data processing or machine learning** – Use Python (for example, [Pandas](https://pandas.pydata.org), [NumPy](https://numpy.org), [Scikit-learn](https://scikit-learn.org/stable/), [TensorFlow](https://www.tensorflow.org), [PyTorch](https://pytorch.org)). - **Web or browser-based integrations** – Use JavaScript. - **External integrations** – Pick what fits the systems you connect to. - **C#** – Best for the Microsoft ecosystem (for instance, [Azure](https://azure.microsoft.com/en-us/) or [SQL Server](https://www.microsoft.com/en-us/sql-server)). - **Python** – Strong community libraries for cloud and data services. - **JavaScript** – Excellent support for web APIs. - **Deployment environment** – Choose what fits your hosting model. - **Serverless** ([AWS Lambda](https://aws.amazon.com/lambda/), [Azure Functions](https://azure.microsoft.com/en-us/products/functions), [Google Cloud Functions](https://cloud.google.com/functions), and [Cloud Run](https://cloud.google.com/run)) – All SDKs work. Prefer the one with the best tooling in your platform. - **Containers** ([Kubernetes](https://kubernetes.io), Optimizely Connect Platform (OCP)) – Any SDK works. Choose based on the team's skill set. ## Next steps When you have chosen an SDK, see the following SDK documentation for step-by-step instructions on usage and create your custom tool: - [JavaScript](https://www.npmjs.com/package/@optimizely-opal/opal-tools-sdk) - [Python](https://pypi.org/project/optimizely-opal.opal-tools-sdk/) - [C#](https://www.nuget.org/packages/OptimizelyOpal.OpalToolsSDK) After creating your custom tool, see [Add a custom tool to Mark](docId:1GdHO3DW4xZfN08J9ns92). :::hint{type="info"} **Note** If you use Opti ID, administrators can turn off generative AI in the Opti ID Admin Center. See [Turn generative AI off across Optimizely applications](docId\:X5U0kKD2azV5cIdNqwGNj). :::