Tool callingTutorial7 min

Build a tool-calling workflow with clear function boundaries

How to design tools that let a model act inside a workflow without gaining broad, unsafe access to your product.

Real example

Example: let AI search tenders, not edit tender records

An assistant needs to help a proposal team find relevant tenders. It should search, compare, and summarize records, but it should not change eligibility status or archive opportunities by itself.

Expose read-only tools such as search_qualified_tenders and get_tender_documents first. Keep destructive or workflow-changing actions behind explicit user approvals, server authorization, and ordinary UI buttons.

The model becomes useful for discovery and explanation while the product keeps ownership of final state transitions.

Narrow custom tool definition

const searchQualifiedTenders = {
  type: "function",
  name: "search_qualified_tenders",
  description: "Find tender records that match an approved industry, deadline, and region filter.",
  parameters: {
    type: "object",
    additionalProperties: false,
    required: ["industry", "deadlineBefore", "region"],
    properties: {
      industry: { type: "string" },
      deadlineBefore: { type: "string", description: "ISO date" },
      region: { enum: ["EU", "US", "Balkans", "Global"] },
    },
  },
};

Tutorial path

How to implement it

Step 01

Name tools after the business action, such as searchQualifiedTenders or createHandoffSummary.

Step 02

Keep the input schema small and use IDs from your system instead of letting the model invent resources.

Step 03

Validate tool arguments before execution and reject unknown fields.

Step 04

Return structured, minimal data that helps the next model step without leaking unrelated records.

Step 05

Log tool requests, execution result, duration, and authorization decision.

Checklist

Ready when these are true

Server-side authorization

Argument schema validation

No destructive tool without approval

Operational logging

Tool output is scoped to the workflow

Field notes

What matters in practice

Tools should express product capabilities, not database tables.

Every tool needs narrow inputs, predictable outputs, and explicit authorization.

The model can request a tool call, but your server decides whether it is allowed.

Avoid these mistakes

Common failure modes

Do not expose a generic run_sql or update_record tool.

Do not let the model supply tenant, role, or owner values.

Do not return records the current user cannot see in the product UI.

Practical tip

Name tools after business actions. A tool called search_qualified_tenders is easier to reason about than one called query_database.

Apply this to a build