Tools & provider adapters

Two APIs, two directions#

Your application calls muwkl’s /v1 API with a workspace key. In the other direction, muwkl calls your provider adapter to read business records or perform a permitted action. The provider credential is separate from your workspace API key.

For example, a service company can expose request.status for checking an existing request, then add request.create as a separate mutating tool. These names belong to your adapter; muwkl does not assume what your business calls a record.

Describe the available tools#

Discovery reads GET /.well-known/agent-provider on the provider origin using its stored bearer credential. A manifest declares protocol_version, contract_version, capabilities, languages and tools. Here is a valid minimal read-only manifest.

{
  "protocol_version": "1",
  "contract_version": "2026-09-01",
  "capabilities": [
    "read"
  ],
  "languages": [
    "en",
    "ar"
  ],
  "tools": [
    {
      "name": "request.status",
      "mutating": false,
      "produces_evidence": [
        "entity",
        "value"
      ],
      "timeout_ms": 5000,
      "parameters": {
        "type": "object",
        "properties": {
          "reference": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          }
        },
        "required": [
          "reference"
        ],
        "additionalProperties": false
      }
    }
  ]
}

Receive a tool call#

muwkl sends POST /tools/{tool_name} with arguments and a context object. Context includes the workspace, conversation, turn, channel-asserted subject, locale, timezone and current time. Tool parameters cannot redefine these context fields.

Calls carry Contract-Version and Trace-Id. A mutation also carries Operation-Id and Request-Fingerprint. Validate inputs against the declared closed JSON Schema before reading or changing your records. The supported timeout_ms is 1–10,000 milliseconds.

Give actions a durable receipt#

A mutating tool declares mutating: true, an action name, the mutate capability and action in produces_evidence. Its manifest also declares receipt_retention_seconds. Store the operation identity, request fingerprint and result together with the business change.

The same operation and fingerprint must resolve to the same recorded outcome. A changed fingerprint is a conflict. After an uncertain response, the platform can inspect the original receipt rather than treat a new attempt as a new business request.

Return evidence the reply can use#

The provider contract distinguishes entity, value, action, reference and completeness evidence. Declaring a kind in the manifest is only the start: the response envelope must satisfy its evidence contract. A bare success string is not an action receipt.

Protected facts and action confirmations are rendered from validated source evidence. Free prose is scanned on a best-effort basis and may contain unsupported assertions.