Create Tool Manager packages

Use this guide when an AI assistant must generate a JSON package for Tool Manager. A package configures a supported HTTP or MCP integration; it does not install an external server, run arbitrary source code as a package, or grant access to an agent automatically. For a tool already available in Weles, prefer the built-in tool catalogue. Start with the AI agent overview.

Decide what to generate

Obtain the target API contract or MCP server details from the user or verified documentation. Identify the operation, URL or transport, input parameters, authentication, returned data, required permissions, and whether it writes data. Ask for the name of a secret, not its value. Do not invent a real endpoint or claim an integration is functional without testing. Create two separate artifacts when both are needed:

A tool package JSON installed in Tool Manager. It defines what the tool calls and which arguments the model may provide.
A workflow import JSON whose agent stage references the installed tool by installed__<slug>. Importing the workflow does not install the package or its secrets.

Package format

The Tool Manager accepts a JSON object with the following fields. The install API is POST /admin/tools/install, authenticated as an administrator, with this object as its JSON body. The UI can import a JSON file, pasted JSON, or a URL, then shows a preview before installation.

Field	Type	Meaning
`name`	string	Human-readable tool name; required by the UI.
`slug`	string	Unique installation identifier. Use lowercase letters, digits and underscores; a duplicate produces a conflict.
`type`	string	One of `http`, `mcp_server`, `mcp_sse`, `mcp_stdio`, `mcp_streamable_http`.
`version`	string	Package version; defaults to `1.0.0`. It does not update an existing slug.
`description`	string	Explain the tool’s purpose, constraints, and when to use it.
`icon`, `category`	strings	Optional display metadata.
`secrets_required`	string array	Vault secret names shown for setup and status; list all names referenced in `config`. Declaring one does not create it or ensure it resolves.
`config`	object	Connection and invocation settings. Secret placeholders in this object are resolved at runtime.
`input_schema`	object	For HTTP packages, the function parameters presented to the model: object `properties` and `required` array. Use the actual API contract.
`auto_discover`	boolean	Optional MCP package setting, defaults to `false`; do not assume it automatically exposes every remote tool.

Only supported package fields are persisted by the install endpoint; do not rely on arbitrary extra metadata to affect execution. Installation validates type and slug but is not a full integration or security test. Existing packages with the same slug are not overwritten.

HTTP configuration and secret references

An http package uses config.url, method, optional headers, timeout, static_body, and optionally body_template. Values in config can contain vault placeholders such as {{KB_SEARCH_URL}} and {{KB_API_KEY}}; store the actual values separately under Secrets. Names must start with an uppercase letter and contain only uppercase letters, digits, and underscores. Resolution recursively walks package config, not arbitrary workflow fields or the provider configuration. Missing or undecryptable secrets can remain unresolved; check secret status and test rather than assuming success. For HTTP calls, parameters declared in input_schema.properties are provided by the model. URL {param} placeholders are substituted from arguments; query placeholders are handled as query parameters. For GET/HEAD, remaining declared parameters become query parameters. For other methods, inputs may be merged with static_body or rendered using body_template. The implementation can send a single string-valued body field as raw text rather than an object. Verify the actual payload and response against the service contract, especially for writes; do not rely on generic POST assumptions.

HTTP URLs, headers, parameters, responses, and logs can expose sensitive information. Use trusted, approved services and least-privilege credentials; review logging and retention. Prefer read-only operations when possible and require authorization before enabling tools that send data or modify systems.

Complete example: tool package and agent workflow

This example connects an agent to a hypothetical read-only knowledge search API. It assumes the endpoint accepts GET query parameter query, an X-API-Key header, and returns useful search results. These are example contract assumptions, not a built-in service. Obtain a real approved endpoint and test its contract before use. llama3 is illustrative; replace it with a target model that supports tool calling. No real secret values are included.

File 1: `knowledge-search-tool.json`

{
  "name": "Knowledge Search",
  "slug": "knowledge_search",
  "version": "1.0.0",
  "description": "Search approved company knowledge by query. Use for questions about internal policies.",
  "icon": "search",
  "category": "knowledge",
  "type": "http",
  "secrets_required": ["KB_SEARCH_URL", "KB_API_KEY"],
  "config": {
    "url": "{{KB_SEARCH_URL}}",
    "method": "GET",
    "headers": {"X-API-Key": "{{KB_API_KEY}}"},
    "timeout": 30
  },
  "input_schema": {
    "type": "object",
    "properties": {
      "query": {"type": "string", "description": "Search terms for approved company knowledge"}
    },
    "required": ["query"]
  },
  "auto_discover": false
}

File 2: `knowledge-assistant-workflow.json`

{
  "export_version": "1.0",
  "workflow": {
    "name": "Knowledge assistant example",
    "description": "Answer questions using an approved knowledge search service.",
    "mode": "agent_only",
    "stages": [
      {
        "name": "API Input",
        "order_index": 1,
        "is_start": true,
        "is_end": false,
        "is_verification": false,
        "stage_type": "agent_input",
        "configuration": {}
      },
      {
        "name": "Knowledge assistant",
        "order_index": 2,
        "is_start": false,
        "is_end": true,
        "is_verification": false,
        "stage_type": "agent",
        "configuration": {
          "agent_config": {
            "model_name": "llama3",
            "system_prompt": "Use Knowledge Search when company information is needed. Distinguish evidence from uncertainty and do not invent facts. Return a JSON object with an answer key.",
            "temperature": 0.2,
            "max_tokens": 4096
          },
          "tools": [
            {"tool_type": "installed__knowledge_search", "name": "Knowledge Search", "config": {}}
          ],
          "input_vars": ["input_question"],
          "output_vars": ["answer"],
          "batch_execution": "per_document"
        }
      }
    ]
  },
  "document_types": {}
}

The tool_type is the literal prefix installed__ followed by the installed package’s slug. Installed tools are looked up by slug and must be enabled. Their connection configuration comes from the installed package; do not expect the workflow tool’s config to override it. The model decides whether to call the tool and may fail to return the requested JSON output key. Input selection does not prevent certain file and internal context keys from being passed through.

Install, connect, and test

Review the real API’s read access, data handling, endpoint and authentication. In Secrets, create KB_SEARCH_URL and KB_API_KEY with approved values. Preserve the vault encryption key as described in configuration. Never place secret values in either JSON file.
Save file 1 as UTF-8 JSON. In Tool Manager → Install Tool → Import, select the file or paste the object, review the preview, and install it. Confirm the tool is enabled and its secret status is configured. If the slug exists already, inspect it rather than assuming the new package replaced it.
Replace the model in file 2 with an available tool-capable agent model. Save and import it through Workflows → Import. Verify the agent stage contains the installed tool; assign authorized users. Configure any other prerequisites and entitlements. Chat uses the chat entitlement; the agent-only invoke API currently checks IDP entitlement.
Test with an approved non-sensitive question and inspect tool-call activity and returned evidence. Confirm the endpoint receives the expected query and that the answer is grounded in the results. Test unavailable service, missing credentials, and empty results. If the tool is not called, inspect model capability and stage configuration; do not present an unverified answer as sourced.

MCP packages

For MCP package types, config is passed to the corresponding Weles MCP integration after secret resolution. HTTP/SSE transports use an endpoint; stdio uses command, args, and optional env. Configure the actual tool_name, schema and authentication fields needed by the transport, and verify discovery and invocation against the target build. MCP package input_schema at the package top level is not a substitute for the MCP integration’s config.input_schema. For Streamable HTTP, verify selected/discovered tool behavior in the target version; do not assume installing one package automatically exposes all remote tools. See MCP tools.

Example: one legacy HTTP MCP tool

This standalone package is only appropriate for a server that supports the legacy mcp_server HTTP JSON-RPC transport and exposes a search tool with the illustrated input schema. Replace the schema and tool name using the server’s actual contract; set the vault secret MCP_SERVER_URL to an approved endpoint. This does not start the MCP server or establish its permissions.

{
  "name": "MCP Knowledge Search",
  "slug": "mcp_knowledge_search",
  "version": "1.0.0",
  "description": "Search approved knowledge using the remote MCP search tool.",
  "type": "mcp_server",
  "secrets_required": ["MCP_SERVER_URL"],
  "config": {
    "endpoint": "{{MCP_SERVER_URL}}",
    "tool_name": "search",
    "input_schema": {
      "type": "object",
      "properties": {"query": {"type": "string", "description": "Search query"}},
      "required": ["query"]
    },
    "timeout": 30
  },
  "input_schema": {},
  "auto_discover": false
}

Install it separately and reference installed__mcp_knowledge_search in an agent stage. Add authentication in config using approved vault references if required. Validate the server’s transport and schema first; an MCP Streamable HTTP endpoint is not necessarily compatible with this legacy example. A stdio package launches a process in the Weles execution environment. Use only a trusted command and arguments, apply OS/container restrictions, and configure an allowed-command policy. A package is not a security sandbox.

Validation checklist for an AI assistant

Parse both files as strict JSON. Check package required fields, unique slug, supported type, schema parameter names and secret references.
Verify the workflow uses installed__ plus the exact slug, and that package and secrets are installed separately. Ensure the stage order and model are valid for the target.
Check the service’s method, endpoint, query/body schema, authorization, error handling, side effects, and expected results against its real API contract.
Supply deployment and rollback instructions without actual credentials. Distinguish example placeholders from validated values.
Do not claim successful integration until an authorized end-to-end test has exercised the target service, model, stage, and access controls.

Getting Started

Administration

Workflows

For AI Agents

Decide what to generate

Package format

HTTP configuration and secret references

Complete example: tool package and agent workflow

File 1: `knowledge-search-tool.json`

File 2: `knowledge-assistant-workflow.json`

Install, connect, and test

MCP packages

Example: one legacy HTTP MCP tool

Validation checklist for an AI assistant

​Decide what to generate

​Package format

​HTTP configuration and secret references

​Complete example: tool package and agent workflow

​File 1: knowledge-search-tool.json

​File 2: knowledge-assistant-workflow.json

​Install, connect, and test

​MCP packages

​Example: one legacy HTTP MCP tool

​Validation checklist for an AI assistant

Decide what to generate

Package format

HTTP configuration and secret references

Complete example: tool package and agent workflow

File 1: `knowledge-search-tool.json`

File 2: `knowledge-assistant-workflow.json`

Install, connect, and test

MCP packages

Example: one legacy HTTP MCP tool

Validation checklist for an AI assistant