• Book: Prompt Engineering Pocket Guide: Techniques for Getting the Most from LLMs
• Also by me: Thinking in Go (2-book series) — Complete Guide to Go Programming + Hexagonal Architecture in Go
• My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
• Me: xgabriel.com | GitHub

You started the agent with three tools. The system prompt described all three by name, gave each a one-line example, and told the model when to pick which. Six months later the toolset has grown to 28. Product asked for a "look up the customer" tool, then a "look up the customer's last invoice" tool, then six variants of "search the docs". The system prompt was never updated to match. It still names three tools.

The trace logs show what happens next. The model calls a tool that does not exist. It picks search_docs_v1 when the right answer was search_docs_legal. Half the toolset never gets called at all because no string in the system prompt nudges the model toward it. You did not break anything. The prompt and the toolset just drifted apart.

This is one of the highest-impact bugs in production agents and one of the easiest to miss. The toolset is in code. The prompt is in code. They are not the same code, they are not in the same file, and nothing in your CI fails when one moves without the other. The rest of this post walks through detection, measurement, and regenerating the prompt from the toolset.

Symptoms that mean your prompt has drifted

A few distinct shapes show up in traces. They are not the same bug, but they share the same root cause.

Tool-call hallucinations. The model emits tool_use for a name your dispatcher does not recognize. Often the name is a plausible mash-up of two real tools: search_customer_invoices when you have search_customers and get_invoice_by_id. The model is generalizing from the prompt's examples and inventing a tool that fits the gap. The Anthropic API returns the response with a tool_use block. Your code throws a "no such tool" error. The user sees a generic failure.

Orphan tools. A tool exists in the registry, gets shipped to the model on every request, and is never called by the model in production. Sometimes that is correct (the tool is for an edge case that rarely fires). Often it means the tool's description is so weak that the model never picks it, or another tool has a stronger description and always wins. Either way you are paying input tokens to send the schema on every request and getting nothing back.

Ambiguous selection. Two tools could plausibly answer the same question. The model picks one consistently and ignores the other, or worse, picks them at random. Take search_docs_v1 and search_docs_legal. If the prompt does not tell the model which corpus is which, the choice is a coin flip. The user sees inconsistent answers depending on which doc store the model picked that minute.

The shared root is that the prompt does not accurately describe the toolset the model has.

The schema-vs-prompt diff

The first move is mechanical. Get the toolset and the prompt into the same data structure and diff them. You want to know, for every tool in the registry, whether the system prompt mentions it at all, and for every tool name in the system prompt, whether it still exists.

import re
from dataclasses import dataclass

@dataclass
class DriftReport:
    in_registry_only: list[str]
    in_prompt_only: list[str]
    both: list[str]


def diff_prompt_and_tools(
    system_prompt: str,
    tool_schemas: list[dict],
) -> DriftReport:
    registry_names = {t["name"] for t in tool_schemas}
    # Names appear in the prompt as `name`, "name",
    # or bare camel/snake case after "Use the".
    pattern = re.compile(
        r"`([a-z][a-z0-9_]+)`|"
        r'"([a-z][a-z0-9_]+)"'
    )
    mentioned = set()
    for m in pattern.finditer(system_prompt):
        token = m.group(1) or m.group(2)
        mentioned.add(token)

    return DriftReport(
        in_registry_only=sorted(
            registry_names - mentioned
        ),
        in_prompt_only=sorted(
            mentioned - registry_names
        ),
        both=sorted(registry_names & mentioned),
    )

Run this in CI on every change to the system prompt or the tool registry. in_registry_only is the list of tools the prompt forgot. in_prompt_only is the list of tools the prompt still names that no longer exist (these are the ones the model is most likely to hallucinate, because the prompt keeps reinforcing the dead name). both is your healthy intersection.

The diff catches the static drift but not the second-order kind. A tool can be in the prompt by name and still be misdescribed. The prompt might say search_docs returns "the top 5 results" when the implementation actually returns 10, and the model will trust the prompt over the runtime behavior every time.

Coverage telemetry

The runtime version of the diff is a coverage histogram. For every tool in the registry, count how often it was selected over the last N requests. The shape of that distribution tells you which tools are orphans, which are dominant, and which are flapping.

from collections import Counter
from anthropic import Anthropic

def coverage_histogram(traces, registry):
    counts = Counter()
    for trace in traces:
        for block in trace["content"]:
            if block["type"] == "tool_use":
                counts[block["name"]] += 1
    rows = []
    for tool in registry:
        rows.append({
            "tool": tool["name"],
            "calls": counts[tool["name"]],
            "share": counts[tool["name"]] / max(
                1, sum(counts.values())
            ),
        })
    return sorted(rows, key=lambda r: -r["calls"])

A healthy toolset has a long tail. Two or three tools dominate, the rest fire occasionally for edge cases. What you do not want is a step function: three tools at 95% of all calls, 25 tools at zero. That zero column is the orphan list, and every one of those tools is paying input-token rent on every request. Per Anthropic's tool-use documentation, tool definitions count toward the input. A forgotten tool with a 200-token schema costs you on every call until you remove it.

Set an alert: any tool with zero calls over the last 1,000 requests gets flagged. A human reviews it and decides whether to delete it from the registry or rewrite its description so the model has a reason to pick it. Either path works; ignoring the orphan does not.

Why descriptions stop matching after a while

Tool descriptions rot the same way comments rot. The first version was hand-written by the engineer who added the tool. They knew the call sites, the failure modes, and the right vocabulary, so they wrote a clear paragraph. The second version was added in a hurry by someone fixing a different bug. They copy-pasted the first description and changed a word. By the tenth tool, the descriptions are inconsistent in tense, length, and terminology. Two tools have a <example> block, six have none, the rest have a half-finished one.

The model reads all of them. It treats the inconsistency as signal. A long, detailed description outranks a short one, regardless of which tool is actually right for the request. A description that uses the same vocabulary as the user's question outranks a description that does not, regardless of which tool is right. The ranking has shifted away from tool capability and onto the prose quality of whoever wrote the description on a Tuesday.

Two fixes work. The first is a description style guide that every new tool has to match (length range, required sections, vocabulary). The second is to skip the prose and generate the description from the schema directly.

Auto-generating descriptions from JSON Schema

If the tool's input schema is rich enough, the description writes itself. You walk the JSON Schema, pull the title, the parameter names and descriptions, and any examples, and template them into a deterministic format. Every tool ends up with the same shape, which kills the prose-quality bias.

def describe_tool(tool: dict) -> str:
    schema = tool["input_schema"]
    name = tool["name"]
    purpose = schema.get("description", "").strip()
    props = schema.get("properties", {})
    required = set(schema.get("required", []))

    param_lines = []
    for key, spec in props.items():
        marker = "required" if key in required else "optional"
        desc = spec.get("description", "").strip()
        param_lines.append(
            f"  - {key} ({marker}): {desc}"
        )

    examples = schema.get("examples", [])
    example_block = ""
    if examples:
        example_block = "\nExample input:\n" + "\n".join(
            f"  {e}" for e in examples[:1]
        )

    return (
        f"Tool: {name}\n"
        f"Purpose: {purpose}\n"
        f"Parameters:\n"
        + "\n".join(param_lines)
        + example_block
    )

Now your tool registry stores the schema. The system prompt is generated at request time from the schemas, with a one-line preamble per tool. If you add a parameter to search_customers, the description regenerates. The prompt and the tools cannot drift, because there is only one source.

You pay a small cost: the auto-generated descriptions are blander than a hand-written one. A hand-written description can say "use this for cross-team docs only, not the legal corpus", which the schema cannot express. The trade is consistency for craft. Hand-writing wins under ten tools. Somewhere between ten and twenty, the consistency dividend starts beating individual craft, and past twenty, generation pulls ahead by a wide margin.

The tool-router pattern

If your toolset is large enough that the schema-vs-prompt diff keeps growing, the next move is to stop showing every tool to the model. A tool router is a small upstream classifier (an embedding-similarity match, or a cheap-model classification) that picks 3 to 5 candidate tools per request and only those go into the prompt.

The shape:

def select_tools(query: str, registry):
    # Pre-computed at registry load time.
    embeddings = [t["embedding"] for t in registry]
    query_emb = embed(query)
    scored = [
        (cosine(query_emb, e), t)
        for e, t in zip(embeddings, registry)
    ]
    scored.sort(reverse=True)
    return [t for _, t in scored[:5]]


def call_agent(query: str, registry):
    selected = select_tools(query, registry)
    return client.messages.create(
        model="claude-opus-4-5-20250929",
        max_tokens=2048,
        tools=selected,
        messages=[{"role": "user", "content": query}],
    )

The model now sees the 5 tools that look most relevant to the query, not all 28. Hallucination drops because the prompt is shorter and more focused, and orphan tools stop paying token rent on every request. Ambiguous selection drops too: the router does the first cut, leaving only tools that pass a similarity threshold.

The cost is misroute risk. The router excludes the right tool from the candidate set and the model has no way to recover. Mitigate it two ways. First, evaluate the router with a held-out set of (query, expected_tool) pairs and watch top-5 recall. Second, keep a "fallback" tool always in the candidate set that lets the model say "none of these match, escalate." A span attribute carrying the selected tool names per request lets you spot the misroutes in production.

What to do with this on Monday

A short sequence to run before the week ends.

Run the schema-vs-prompt diff on your current agent in CI. If the diff returns anything in in_prompt_only, ship a fix today; those names are actively pulling the model toward a tool that does not exist. Then build the coverage histogram off your last 1,000 traces. Anything in the registry with zero calls is either dead code or has a description the model never picks, so decide today which it is, and delete or rewrite accordingly.

Once the current state is clean, put the next checkpoint on the calendar. Tool registries grow whether you watch them or not, and the drift is silent until a user complains. A two-hour audit every quarter beats an outage when the model invents a tool it heard about three releases ago.

The prompt is part of the toolset. Keep them in the same source, regenerate one from the other where you can, and watch the drift number rather than waiting for a hallucinated tool name to surface it for you.

If this was useful

Prompt Engineering Pocket Guide: Techniques for Getting the Most from LLMs covers the prompt-shape questions hiding behind every tool-use design: how long a tool description should be, when a one-tool-per-question router beats a 28-tool prompt, and what happens to selection accuracy as you cross 10, 20, 50 tools. The book is short on purpose; it is the chapters you would have written after a year of running the harness.