Custom tools FAQ
If your custom Optimizely Agent Platform 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 Agent Platform?
Agent Platform relies on your tool manifest and discovery endpoint to understand and register your tool. If either is misconfigured, Agent Platform 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 Agent Platform’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 Agent Platform not discover my tool?
Agent Platform discovers tools through the /discovery endpoint. If this endpoint is inaccessible, Agent Platform 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 Agent Platform 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 Agent Platform registry must have a unique name or key. If two tools share the same name or key, the following might happen:
- Agent Platform might only register one instance.
- Mark may behave unpredictably.
Solution – Verify that your tool's programmatic name and key are unique in the context where it is deployed.
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.