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

# Create Tool Manager packages

> Generate installable HTTP and MCP tool packages and connect them to an agent workflow.

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](https://docs.welesai.com/workflows/agent-tools.md). Start with the [AI agent overview](https://docs.welesai.com/ai-agents/start-here.md).

## 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:

1. A **tool package JSON** installed in **Tool Manager**. It defines what the tool calls and which arguments the model may provide.
2. 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.

> [!WARNING]
>
> 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`

```json theme={null}
{
  "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`

```json theme={null}
{
  "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

1. 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](https://docs.welesai.com/administration/configuration.md). Never place secret values in either JSON file.
2. 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.
3. 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.
4. 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](https://docs.welesai.com/workflows/agent-tools.md#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.

```json theme={null}
{
  "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.


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