AI can't see a clock. So how did it tell me the time?

A language model is a function from input tokens to output tokens: it has no clock, no network and no file system, so it cannot know what time it is unless something puts the time into its input. Tool calling is the mechanism that lets the model ask the surrounding app to run code, such as reading a clock, and get the result back as text. Interview version: "How does an LLM app answer questions that need live data, and what does the extra step cost?"

Prerequisites

What one model request contains. Every call to a chat model is stateless: the app sends the instructions, the conversation so far and any extra data, and nothing persists inside the model between calls. The context window article (AI 3) shows what the app resends each turn. This article adds two more kinds of content to that request: tool definitions and tool results.

Tokens and generation. A model writes its output one token at a time; the streaming article (AI 2) explains that loop and its timing. A tool call is a reply whose tokens form a structured request instead of prose.

Remote calls. When one program asks another to run a function and return the result, that is a remote procedure call (RPC): a name, arguments, a result or an error, and a network trip in between. Part 47 of the series covers RPC and gRPC in depth.

Definitions

Why can a model not know the time?

A model's output is computed from two things only: its weights, fixed when training ended, and the tokens in the current request. No hidden register holds the time. If the request does not say what "now" is, the model cannot compute it.

The weights do give a rough sense of the period the training data came from: the training cutoff. But a model is released some time after its cutoff and then used for a long time, so the distance between "the last thing it read about" and "today" is unknown to it and grows every day.

So without help, a model asked "What time is it in Tokyo?" can refuse, guess, or use something in its input. Our lab scripts the first two on purpose. In mode A of labs/ai-5, a scripted toy model with no tool refused in 11 of 20 runs and guessed in 9, always a random time on a fixed date, 2025-06-01, written into the code as an assumption. Against a virtual clock at 2026-11-05 23:00 Tokyo time, the median guess was off by 752,645 minutes = 752,645 / 1,440 = 522.7 days. That number follows entirely from the assumed date; it is not a measurement of any real model. Still, with nothing in the input, being right is luck.

There are two ways to put "now" into the input:

1. The app writes it into the prompt. App code reads the server clock and adds Current date: 2026-11-05 (Thursday). User timezone: Asia/Tokyo. to the system prompt. Zero extra round trips.
2. The app offers a tool. The model asks for the time, with arguments, when it needs it. One extra round trip per use, but exact at that moment and for any timezone.

Either way, app code reads the clock. The rest of this article covers the second, which generalises to all live data and actions.

How it works: one tool call, step by step

Tool APIs use different field names, but the shape is the same (compare the Anthropic tool use guide and the OpenAI function calling guide). One complete exchange for the Tokyo question:

Step 1: the app sends the question and the tool list. Each tool has a name, a description written for the model, and a JSON Schema for its arguments:

{
  "name": "get_current_time",
  "description": "Returns the current local time for an IANA timezone such as Asia/Tokyo.",
  "input_schema": {
    "type": "object",
    "properties": {
      "timezone": { "type": "string", "description": "IANA timezone name" }
    },
    "required": ["timezone"],
    "additionalProperties": false
  }
}

The provider renders these definitions into the model's input in a format the model was trained on. So definitions cost input tokens on every request, and the description is effectively prompt text: a vague description produces vague tool use.

Step 2: the model emits a tool call instead of a reply. The model was trained to produce a structured block when a tool would help. The API parses it and returns it as data, with a stop reason meaning "I want a tool" (stop_reason: "tool_use" in Anthropic's Messages API, finish_reason: "tool_calls" in OpenAI's Chat Completions API). The call carries a unique id, the tool name and the arguments:

{ "type": "tool_use", "id": "call_01", "name": "get_current_time", "input": { "timezone": "Asia/Tokyo" } }

Some APIs give the arguments as an object, others as a JSON string. Either way they are generated tokens that can be malformed or wrong: untrusted input to your system.

Step 3: the app checks and runs the tool. Ordinary application code looks up the name, checks permissions, validates the arguments, runs the function with a timeout and captures the output or error. In the lab, this is the only place the clock is read:

app runs tool  [sim 1 ms] {"timezone":"Asia/Tokyo","local":"2026-11-05 23:10:15",
                           "utc_offset":"+09:00","utc_iso":"2026-11-05T14:10:15.459Z"}

Step 4: the app sends a new request with the result. It appends the model's tool-call message as returned, plus a tool result message referencing the same id (tool_use_id, tool_call_id or call_id, depending on the API), and calls the model again. The model is stateless, so this follow-up carries everything: instructions, tool definitions, question, tool call and result.

Step 5: the model writes the final reply from the result. The time is now in its input as text: "It's 23:10 on 2026-11-05 in Tokyo right now."

In the lab code the scripted model function receives only messages and never touches clock.now. The model asks, the app's code does the work, the answer returns as text. "The AI used a tool" means exactly that exchange.

What does the app check before it runs a tool?

The model's output decides which function runs with which arguments, so a tool call is an entry point into your system, like an HTTP request from the internet. Anything that influences the model's output (the user, a web page it read, a document it summarised) influences the call. So the app checks, in order:

1. Is the tool known? Look the name up in a fixed registry. Never map a model-written string to an arbitrary function or shell command.
2. Is this caller allowed to use it? An allow-list per user, session or feature. Filter the tools you offer, and check again at execution time, because the model can name a tool that was not offered.
3. Are the arguments valid? Parse the JSON and validate against the schema: types, required fields, no unknown fields, patterns, ranges. Then validate meaning, which a schema cannot express: is Asia/Tokyo a real IANA zone, is this path inside the user's folder, does this account belong to this user.
4. Does it need a human? Read-only tools such as a clock can run automatically. Side effects (email, deleting files, moving money) need explicit confirmation showing the exact arguments, and idempotency so a repeat does no extra harm.
5. Within limits? Per-tool rate limits, a timeout per call, and a cap on result size, since the result returns to the context window as paid input tokens.

Schema-constrained generation, where offered, removes malformed JSON, not wrong values or unauthorised intent.

What is the agent loop, and when does it stop?

Step 4 is a loop in disguise: after a result, the model may ask for another tool (look up the user's city, then the time there). The app continues until the model replies without a tool call:

messages = [system, user]
for step in 1..MAX_STEPS:
    reply = model(messages, tools)
    messages += reply
    if reply has no tool calls: return reply.text
    for each call in reply.tool_calls (in parallel when independent):
        result = check_and_run(call)          # errors become results too
        messages += tool_result(call.id, result)
stop: "gave up after MAX_STEPS model calls"

Nothing in the model guarantees it stops asking, so the loop needs explicit stop conditions:

• Maximum steps. A hard cap on model calls per request. Without it, a model that keeps requesting a tool (or a tool that keeps failing) burns tokens until something else breaks.
• Budget. A cap on tokens, tool time or wall-clock time. Each turn resends the growing conversation, so total input tokens across one request grow roughly with the square of the number of turns when results are large.
• Repeat detection. The same tool with the same arguments twice in a row, after a success, signals a problem: send a short note to the model or stop.
• A clear end state. On a limit, return a defined "could not finish" outcome and log the full trace.

Most APIs also offer a tool choice setting (auto, force a tool, forbid tools). Leaving the choice to the model is what makes the loop an agent rather than a script.

What does a tool call cost in latency?

A tool step adds one full model round trip, not just the tool's own time. For a request with k sequential tool steps:

model calls  = k + 1
total time  ≈ Σ (model call i)  +  Σ (tool time in step j)

with parallel calls inside one step:
tool time of a step = max(tool times), not the sum

The lab records this inside each tool-using run rather than subtracting medians of separate samples. All of it is simulated with assumed ranges: first model call 400 to 1,000 ms, follow-up 300 to 800 ms, tool 1 to 5 ms. Across 20 tool-mode runs the median added cost was 484 simulated ms: median tool time 2 ms, median follow-up call 482 ms. The tool is almost free; the second model call is the cost.

The follow-up call is also heavier in tokens: it carries everything the first did plus the call and the result. So a tool returning a 50 KB JSON document when the model needs one field is a latency and cost bug. As the latency vs throughput article shows, more parallel capacity does not shorten a chain of dependent steps.

Ways to reduce the cost:

1. No tool for stable facts. Today's date and the user's timezone change once a day; put them in the system prompt. Place them after the large stable part (instructions, tool definitions), at day granularity, so provider-side prefix caching, where offered, still reuses the stable prefix. A timestamp with seconds at the top makes every prefix unique.
2. Parallel tool calls. Tokyo and London times can be requested in one turn and run concurrently: one step instead of two, saving a model round trip.
3. Cache tool results that are safe to reuse briefly (an exchange rate for 60 seconds). Never cache the clock or side effects.
4. Shrink tool results to the fields the model needs.
5. Stream the final reply (see the streaming article) and show "checking the time" during the tool step.

Why a tool call is just RPC

Strip away the model and the exchange is familiar: a function name and serialized arguments go to something that runs the function elsewhere and returns a result or an error. That is a remote procedure call. The only new part is that a model decides when to call and with what arguments.

The mapping is close enough that RPC lessons transfer directly:

Deadlines. gRPC asks every caller to set a deadline, because a call without one can wait forever holding resources (see the gRPC deadlines guide). A fetch tool hanging for 60 seconds stalls the whole agent loop for 60 seconds. Give each tool a timeout and the request an overall budget.

Errors as results. An RPC client turns an error into an exception. In an agent loop it is usually better to return the error to the model in plain words ("unknown timezone Mars/Olympus_Mons; use an IANA name like Asia/Tokyo"), so it can fix the argument, try another tool or explain. Keep errors the model cannot fix (authentication failures, an exhausted budget) on the app side.

Idempotency and retries. A model may repeat a call after a timeout, and the app may retry a step. For get_current_time that is harmless; for send_payment it is a double charge. Treat side-effecting tools as non-idempotent RPCs: one idempotency key per intended action (the tool call id is a natural one), and reject a second execution with the same key.

Availability. Every tool is a dependency in series with the model: a request needing both succeeds only when both are up, the product rule from two servers in a row.

Worked example

The video's question, "What time is it right now in Tokyo?", runs 20 times without tools and 20 times with get_current_time. All behaviour comes from a scripted toy model with assumed rates (refuse 45% without a tool, skip the tool 5%, timezone slip 5%), a virtual clock from 2026-11-05 23:00 Tokyo time, and simulated latency.

Mode A, no tool (scripted)
  refusals                          11 / 20
  guesses                            9 / 20, all on the assumed date 2025-06-01
  median guess error                 752,645 min / 1,440 = 522.7 days
                                     (2025-06-01 to 2026-11-05 is 522 days, plus the time-of-day gap)

Mode B, with get_current_time (scripted)
  called the tool                   20 / 20
  within 1 minute of virtual clock  20 / 20
  median error                       29.1 s
    why not 0: the reply says "23:10", rounding 23:10:15 down to the minute,
    and the virtual clock moves on during the follow-up call, so the error
    is (seconds dropped) + (follow-up time), somewhere between 0 and about 61 s

Added cost per tool run (simulated, median of per-run values)
  tool                               2 ms
  follow-up model call             482 ms
  total added                      484 ms   (median of the per-run sums)

The printed trace: the first model call (992 simulated ms) returns get_current_time({"timezone":"Asia/Tokyo"}), the app runs it in 1 simulated ms and gets 2026-11-05 23:10:15, and the follow-up call (585 simulated ms) writes "It's 23:10 on 2026-11-05 in Tokyo right now."

The assumed 5% timezone slip did not fire in these 20 runs with this seed. Had it fired, the scripted model would have read the utc_iso field (14:10) as Tokyo time: an error of exactly 9 hours = 540 minutes, since Tokyo is UTC+9 all year.

Code

A complete agent loop in one file: a tool registry with JSON Schema arguments, an allow-list, a small validator, per-tool timeouts, parallel calls, errors returned as results and a maximum-steps guard. The model is a fake that reads only messages, so no API key is needed. Node.js 18 or newer, no packages.

// agent_loop.mjs: a tool-calling agent loop with a fake model. Node 18+, no packages, no network.
// The fake model only reads messages. Only the app's tool code reads the clock.

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
const MODEL_MS = 150;        // pretend one model round trip takes 150 ms (an assumption)
const TOOL_TIMEOUT_MS = 500; // the app gives each tool call at most 500 ms
const MAX_STEPS = 4;         // the app stops the loop after 4 model calls

// 1. Tool definitions: a name, a description and a JSON Schema for the arguments.
const TOOLS = {
  get_current_time: {
    description: 'Current local date and time for one IANA timezone, e.g. Asia/Tokyo.',
    parameters: {
      type: 'object',
      properties: { timezone: { type: 'string', pattern: '^[A-Za-z_]+(/[A-Za-z_]+)+$' } },
      required: ['timezone'],
      additionalProperties: false,
    },
    run: async ({ timezone }) => {
      const now = new Date();               // the only line in this file that reads a clock
      const local = new Intl.DateTimeFormat('sv-SE', {
        timeZone: timezone, dateStyle: 'short', timeStyle: 'medium',
      }).format(now);                       // throws RangeError for an unknown timezone
      return { timezone, local, utc_iso: now.toISOString() };
    },
  },
  delete_file: {
    description: 'Deletes a file.',
    parameters: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },
    run: async () => ({ deleted: true }),   // never reached: not on the allow-list
  },
};
const ALLOWED = new Set(['get_current_time']); // what this user may run, checked by the app

// 2. A tiny validator for the schema subset used above.
function validate(schema, args) {
  if (typeof args !== 'object' || args === null) return 'arguments must be an object';
  for (const k of schema.required ?? []) if (!(k in args)) return `missing ${k}`;
  for (const [k, v] of Object.entries(args)) {
    const p = schema.properties?.[k];
    if (!p) { if (schema.additionalProperties === false) return `unknown field ${k}`; continue; }
    if (p.type === 'string' && typeof v !== 'string') return `${k} must be a string`;
    if (p.pattern && !new RegExp(p.pattern).test(v)) return `${k} does not match ${p.pattern}`;
  }
  return null;
}

// 3. The fake model: it sees messages and tool names, never the clock.
let nextId = 1;
async function fakeModel(messages, toolNames) {
  await sleep(MODEL_MS);
  const user = messages[0].content;
  const results = messages.filter((m) => m.role === 'tool').map((m) => JSON.parse(m.content));
  const call = (name, args) => ({ id: `call_${nextId++}`, name, arguments: JSON.stringify(args) });
  if (user.includes('loop forever')) return { role: 'assistant', tool_calls: [call('get_current_time', { timezone: 'Asia/Tokyo' })] };
  if (results.length === 0) {
    if (user.includes('delete')) return { role: 'assistant', tool_calls: [call('delete_file', { path: '/tmp/x' })] };
    const zones = [...user.matchAll(/[A-Z][a-z]+\/[A-Za-z_]+/g)].map((m) => m[0]);
    if (zones.length && toolNames.includes('get_current_time')) {
      return { role: 'assistant', tool_calls: zones.map((tz) => call('get_current_time', { timezone: tz })) };
    }
    return { role: 'assistant', content: 'I have no clock, so I cannot know the current time.' };
  }
  const lines = results.map((r) => (r.error ? `error: ${r.error}` : `${r.timezone} ${r.local.slice(11, 16)}`));
  return { role: 'assistant', content: lines.join(' · ') };
}

// 4. The app runs one tool call: allow-list, parse, validate, run with a timeout.
async function runTool(tc) {
  const tool = TOOLS[tc.name];
  if (!tool) return { error: `unknown tool ${tc.name}` };
  if (!ALLOWED.has(tc.name)) return { error: `tool ${tc.name} is not allowed here` };
  let args;
  try { args = JSON.parse(tc.arguments); } catch { return { error: 'arguments are not valid JSON' }; }
  const bad = validate(tool.parameters, args);
  if (bad) return { error: `invalid arguments: ${bad}` };
  const timeout = new Promise((r) => setTimeout(() => r({ error: 'tool timed out' }), TOOL_TIMEOUT_MS));
  try { return await Promise.race([tool.run(args), timeout]); }
  catch (e) { return { error: `${e.name}: ${e.message}` }; } // errors go back to the model as results
}

// 5. The agent loop.
async function agent(prompt) {
  const t0 = performance.now();
  const ms = () => `${Math.round(performance.now() - t0)} ms`.padStart(7);
  const messages = [{ role: 'user', content: prompt }];
  console.log(`\n> ${prompt}`);
  for (let step = 1; step <= MAX_STEPS; step++) {
    const out = await fakeModel(messages, Object.keys(TOOLS));
    messages.push(out);
    if (!out.tool_calls) { console.log(`${ms()}  reply: ${out.content}  (${step} model calls)`); return; }
    for (const tc of out.tool_calls) console.log(`${ms()}  model asks: ${tc.name}(${tc.arguments})`);
    const results = await Promise.all(out.tool_calls.map(runTool)); // parallel tool calls
    out.tool_calls.forEach((tc, i) => {
      console.log(`${ms()}  app returns: ${JSON.stringify(results[i])}`);
      messages.push({ role: 'tool', tool_call_id: tc.id, content: JSON.stringify(results[i]) });
    });
  }
  console.log(`${ms()}  stopped: ${MAX_STEPS} model calls without a final reply`);
}

await agent('What time is it?');
await agent('What time is it in Asia/Tokyo?');
await agent('Time in Asia/Tokyo and Europe/London?');
await agent('What time is it in Mars/Olympus_Mons?');
await agent('Please delete my temp file.');
await agent('Asia/Tokyo, loop forever');

node agent_loop.mjs

What to observe (timings from one run on our Mac; the 150 ms model delay is an assumption):

• "What time is it?" No timezone, so the fake model answers from nothing: one model call, about 150 ms.
• "...in Asia/Tokyo?" Two model calls, about 300 ms. The tool takes about a millisecond; the second model call is the cost. The local and utc_iso fields differ by exactly 9 hours.
• "...Tokyo and Europe/London?" Two tool calls in one step via Promise.all: still about 300 ms, not 450 ms.
• "Mars/Olympus_Mons" passes the schema pattern but Intl.DateTimeFormat throws RangeError, which returns as a tool result. Schema and semantic validation are different layers.
• "delete my temp file" delete_file exists but is not on the allow-list; the app refuses before running anything.
• "loop forever" The loop stops after 4 model calls, about 600 ms, with a defined message.

The article's numbers come from our lab script (labs/ai-5/run.mjs in our public lab repository). It is seeded on a virtual clock, so every run prints the same traces, summary rows and RESULT line; the inputs are listed in the worked example above.

Failure modes and edge cases

Timezone slip. The tool returns a UTC timestamp and a local time, and the model reports the wrong one as local (an assumed 5% in the lab; plausible whenever a result has similar-looking fields). Detect it with tests that compare the reply's hour with the tool's local field. Fix it at the source: return only what is needed, name fields unambiguously (local_time_tokyo, not time), include the offset (RFC 3339, 2026-11-05T23:10:15+09:00), or return a ready-to-say string.

Daylight saving and fixed offsets. A hard-coded +9 works for Tokyo all year and fails for Europe/London, which switches between UTC+0 and UTC+1. Convert with the IANA database (Intl, the OS zoneinfo or a library), never a stored offset, and resolve ambiguous input such as "IST", which names more than one zone.

Stale date in a long session. A date injected once at session start is wrong after midnight. Inject it per request.

The model skips the tool and answers from its weights (an assumed 5% in the lab). If an answer must come from a tool, force tool choice for that step, or check in code that the reply's facts appear in a tool result.

Invented tools and fields. The registry lookup and additionalProperties: false catch them; log them, since a rising rate often means a confusing description.

Hanging tools. Per-tool timeouts and an overall deadline keep the loop moving. Promise.race in the example stops waiting but does not cancel the work; real tools should accept an AbortSignal.

Runaway loops. Repeated or oscillating calls multiply cost. Max steps, a token budget, repeat detection and a per-request trace (each call, arguments, timings) make them visible.

Untrusted text steering tools. A tool result such as a web page can contain instructions the model follows next turn. Treat results as data, keep permissions tied to the user, and confirm side effects. The next part of the series is about this failure.

Trade-offs

Common mistakes

In an interview

1. Clarify: what live data or actions are needed, read-only or with side effects, and what may this user do?
2. Assumptions: a model round trip and a tool time (say 600 ms and 20 ms) and tool steps per question.
3. Structure: client, app server running the agent loop, model API, tool services; mark where permissions, validation and timeouts sit.
4. Deep dive: schema definitions, tool call with an id, app-side checks and execution, tool result, follow-up call; model calls = steps + 1; stop conditions.
5. Trade-offs: prompt-injected facts vs tools, parallel calls, caching, fixed workflow vs open loop, confirmation for side effects.
6. Wrap up: metrics (steps per request, tool error rate, p95 per step, limit hits) and a trace per request.

Practice

Cheat sheet

Further reading

• Anthropic, Tool use with Claude: tool definitions, tool use and tool result blocks, tool choice and parallel tool use, with request examples.
• OpenAI, Function calling: the same flow in another API, including tool call ids, strict schema mode and several calls per turn.
• JSON Schema: the schema language for tool arguments, including required, pattern and additionalProperties.
• gRPC, Introduction: service definitions, stubs and the RPC model tool calling resembles.
• gRPC, Deadlines: why every remote call needs a deadline; the same reasoning applies to tool timeouts.
• IANA Time Zone Database: zone names and daylight saving rules used by operating systems and Intl.
• RFC 3339: the timestamp format with an explicit offset.

Next in the series: a web page hides one sentence, and the AI obeys it. For the queueing side of tool latency, see why a server is fast alone and slow when crowded.

This article describes general patterns for tool calling and agent loops, illustrated with our own small scripted demonstration. The lab numbers come from a scripted toy model with assumed behaviour rates, a virtual clock and simulated latency in one Node.js process. They are not measurements of any company's model, product or private system.