Tools

Tools are how agents act. Every ConsciousLab module provides built-in tools, and you can register your own over HTTP.

Built-in tools

Built-in tools cover the common actions of each module, for example orders.lookup, devices.pause, invoices.create, refund.issue, events.query and trading.quote. They use the same permissions and policies as the console and API. The full list is in the console under AI, Tools.

Register a custom tool

A custom tool is a JSON Schema for its arguments plus an HTTPS endpoint that we call with those arguments.

import { defineTool } from '@consciouslab/sdk';
import { z } from 'zod';

export default defineTool({
  name: 'scans.get',
  description: 'Fetch the inbound scan record for a pallet, including damage flags and photos.',
  input: z.object({
    scanId: z.string().regex(/^RX-\d{4,}$/),
  }),
  endpoint: 'https://wms.halvorsen.example/api/scans',
  timeoutSeconds: 10,
});

Descriptions matter: the model chooses tools based on them. Say what the tool returns and when to use it, in one or two sentences.

Request and response

We send a POST with the validated arguments and a signature header:

POST /api/scans HTTP/1.1
Content-Type: application/json
CL-Signature: t=1760708872,v1=5f2c8e...
CL-Run-Id: run_7Hq2xV

{ "scanId": "RX-4471" }

Verify the signature exactly as you would for webhooks. Respond with JSON within the timeout. Anything you return is shown to the model as the tool result and stored in the trace, so do not return secrets.

Validation

Arguments are validated against the schema before your endpoint is called. If the model produces invalid arguments, it receives the validation error and may try again; your endpoint never sees invalid input. Responses larger than 256 KB are truncated with a note to the model.

Timeouts and retries

The default timeout is 30 seconds, configurable up to 300. On a network error or a 5xx, we retry twice with exponential backoff and the same Idempotency-Key header, derived from the run ID and step. Make your endpoint idempotent on that key if the tool has side effects.

Policies

Every custom tool gets a default policy of require_approval for all calls. Change it once you are confident in the tool's behaviour, ideally after running a new policy in shadow mode for a week.