# Build and use Tools

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

## Before you begin {#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 {#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 {#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 {#next-steps}

Read [Resources and Tools](/docs/sdk/resources-and-tools.md), [Use Resources from Agents](/docs/resources/use.md), and [Operate Runs](/docs/runs/operate.md).