Custom tools FAQ

  • Updated

If your custom Optimizely Opal tool is not functioning as expected, it is often due to problems with the tool manifest or discovery process. The following FAQs cover common causes and how to address them.

Why is my tool not working in Opal?

Opal relies on your tool manifest and discovery endpoint to understand and register your tool. If either is misconfigured, Opal may not correctly identify your tool or its capabilities. Check for the following common issues.

What happens if my tool parameters are defined incorrectly?

Incorrect parameter definitions can prevent Opal’s AI from using your tool effectively. Examples include the following:

  • Using the wrong data type (for example, defining a parameter as a string when it should be a number).
  • Not marking required parameters as required.
  • Writing unclear or ambiguous descriptions.

When parameter definitions are inaccurate, users might enter invalid inputs, causing runtime errors.

Solution – Review each parameter’s name, type, description, and required status to ensure they accurately reflect the tool's expected inputs.

Why can Opal not discover my tool?

Opal discovers tools through the /discovery endpoint. If this endpoint is inaccessible, Opal cannot find or register your tool. Common issues include the following:

  • The endpoint is not publicly accessible.
  • The endpoint returns HTTP errors, such as 404 Not Found or 500 Internal Server Error.
  • There are misconfigurations, such as Cross-Origin Resource Sharing (CORS) problems.

Solution – Ensure your service exposes a working /discovery endpoint and verify that it can be reached from the Optimizely environment.

What causes a malformed manifest error?

A malformed manifest prevents Opal from registering your tool. Typical causes include the following:

  • Having syntax errors in the JSON file.
  • Missing critical fields.
  • Using an incorrect schema.

Solution – Even if you use an SDK to generate your manifest, you should still understand the expected structure so you can debug issues.

What should I do if I get a tool name or key conflict error?

Every tool in an Opal registry must have a unique name or key. If two tools share the same name or key, the following might happen:

  • Opal might only register one instance.
  • Opal may behave unpredictably.

Solution – Verify that your tool's programmatic name and key are unique in the context where it is deployed.

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.