Give an agent tools without it hallucinating

Why it hallucinates

An LLM doesn't lie: it completes. When you ask it to summarize the activity of a repo it can't read, it produces the most plausible continuation — a believable but invented roadmap. The problem isn't the model, it's that we cut off its access to reality.

A tool is a described function

A tool is three things: a name, a description (in natural language — that's what the model reads), and an input schema. The model decides when to call it from the description — so it matters as much as the code.

import { tool } from "@langchain/core/tools";
import { z } from "zod";
// un outil = une fonction + un schema. Le modele l'appelle quand il en a besoin.
const getGitlabActivity = tool(
  async ({ projectId }) => {
    const commits = await gitlab.commits(projectId);   // donnees REELLES
    return JSON.stringify(commits.slice(0, 20));
  },
  {
    name: "get_gitlab_activity",
    description: "Lit les commits reels d'un projet GitLab. A utiliser avant de resumer une roadmap.",
    schema: z.object({ projectId: z.string() }),
  },
);

The model decides, the graph executes

You bind the tools to the model. Each turn, it can either answer or request a tool call. The node executes the call, feeds the result back, and hands control back to the model — that’s the agentic loop.

import { ChatOpenAI } from "@langchain/openai";
// on "donne" les outils au modele — il decide seul quand les appeler
const model = new ChatOpenAI({ model: "gpt-4o" }).bindTools([
  getGitlabActivity,
  listProjects,
  readMemory,
]);
// dans le noeud : si le modele demande un outil, on l'execute et on reboucle
const res = await model.invoke(messages);
if (res.tool_calls?.length) {
  // ... execute les outils, ajoute les resultats, rappelle le modele
}

The guardrails

Giving tools isn't enough: you must frame their use, otherwise the agent loops, over-calls, or ignores the tools and invents anyway.

Design the schema as a contract

The input schema isn't paperwork: it's the contract that stops the model from improvising. In strict mode, the provider guarantees the produced arguments match the schema exactly — no invented field, no fuzzy type. On the Anthropic side you add `strict: true` to the definition; on OpenAI, the same flag requires `additionalProperties: false` and every field in `required` (an optional field is modeled as a union with `null`).

With Zod, you write the schema once and LangChain converts it to JSON Schema for the tool call, then validates and parses the response on the fly — no manual parsing on your end (structured output docs). So the same Zod object both describes the input to the model and checks the output before letting it continue.

Name without ambiguity

A `user` parameter invites the model to guess: an id? a name? an email? A `user_id` parameter leaves no choice. Anthropic sums this up as the “intern test”: if a new hire can't use the tool from the description and field names alone, neither can the model (writing tools for agents).

Catch errors, measure the calls

Even well described, a tool sometimes returns an error, or the model passes an argument your business validation rejects. The right reaction isn't to crash: it's to send the error back *to the model* as a tool result, with an actionable message, so it fixes it on the next turn. Anthropic recommends “specific and actionable” messages over opaque codes (writing tools for agents).

const parsed = ToolInput.safeParse(rawArgs);
if (!parsed.success) {
  // On ne plante pas : on renvoie l’erreur au modèle comme tool_result
  return {
    role: "tool",
    tool_call_id: call.id,
    content: `Validation failed. Fix these fields and retry:\n\${parsed.error.issues
      .map((i) => `- \${i.path.join(".")}: \${i.message}`)
      .join("\n")}`,
  };
}
// parsed.data est typé et validé — on peut exécuter l’outil en confiance
const result = await runTool(parsed.data);

Limit the tool surface

The more tools you give, the more the model picks the wrong target and the more context fills up. Anthropic advises staying under ~20 active tools and consolidating: one `schedule_event` beats `list_users` + `list_events` + `create_event`. Beyond that, switch to on-demand tool discovery instead of loading everything into context.

Evaluate, don’t just hope

“Works on my example” isn't enough. You evaluate tool use at three levels: the final answer, the isolated step (did it pick the right tool?), and the whole *trajectory* (did it follow the right chain of calls?). The `agentevals` package ships ready-made evaluators: strict, unordered, or subset match on the expected tool calls.

Sources & further reading