Documentation / Resources / Use

Build and use Tools

Turn governed Resource operations into clear model-facing capabilities with bounded schemas and truthful effect handling.

Before you begin

Configure the Resource and inspect its immutable operation catalog. Choose the smallest set of operations the model needs. A Tool should express one understandable outcome, validate a bounded argument object, and declare the maximum external effect it can produce.

Steps

  1. Define a Tool with a stable name and version, concise outcome-oriented description, JSON schema, maximum effect, logical Resource needs, and handler.
  2. Resolve the exact accepted Resource from ctx.resources; never accept a Resource CRN or owner identity from model arguments.
  3. Invoke the pinned operation with ctx.invoke() or return the durable handle from ctx.invokeAsync(). Supply a stable dedupe key for idempotent external mutations.
  4. Register the Tool in agent.tools and list its local name in constal.agent.json. The deployment pins the resulting Toolset.
  5. Offer only the needed Tool names in ctx.turn({ tools: [...] }). Policy can narrow the offered set further at each turn.
ts
import type { Tool } from "@constal/sdk";

export const lookupOrder: Tool = {
  name: "lookup_order", version: "1",
  description: "Read the current status of one order.",
  schema: { type: "object", required: ["orderId"], additionalProperties: false,
    properties: { orderId: { type: "string", minLength: 1, maxLength: 128 } } },
  maxEffect: "read-only",
  needs: [{ binding: "orders", kind: "db", ops: ["order.get"] }],
  run(args, ctx) { return ctx.invoke(ctx.resources.orders!, "order.get", args); },
};

opTool(binding, op) and opTools(binding, ops) can derive catalog-backed Tools when the operation contract already supplies the correct schema and effect. Use a custom Tool when the model interface must be narrower or combine controlled steps.

Verify

Deploy and inspect Resources → Tools. Confirm the Tool’s owning Agent, version, description, needs, and enabled status. Start a Run and verify the journal records the Tool call and exact Resource operation separately, with the expected effect, Policy decision, usage, and outcome.

Next steps

Read Resources and Tools, Use Resources from Agents, and Operate Runs.