Tools Shape Behavior

The Story

Forty tools dropped tool-selection accuracy from 97% to 78% in a single release — and the engineering team thought they were adding capability. The e-commerce assistant had been wired to every available API: order lookup, returns, refunds, shipping, search, reviews, seller messaging, coupons, loyalty, address updates, subscriptions, warranty, gift cards, wishlists, and twenty-six more. (An API — Application Programming Interface — is the door a software system exposes so other software can ask it questions or tell it to do something. Each "tool" the AI has is just an API the AI is allowed to call.) The team's reasoning: more tools, more capability. The result was the opposite.

A customer types: "Where is my order?"

The AI has 40 tools available. The relevant one is track_shipment. But the tool descriptions are written in API documentation style: track_shipment(order_id: string) → Returns shipment tracking information including carrier, status, and estimated delivery. The model also sees get_order_details(order_id: string) → Returns complete order information including items, payment, and shipping. Both seem relevant. The model calls get_order_details instead — which returns a JSON blob with 2,400 tokens of order data but no real-time tracking information.

The customer does not get their tracking status. The model, having received the order details, generates a response about what they ordered rather than where it is. The customer asks again. The model calls a different tool. Three turns in, the customer gives up and calls the support line.

The fix was not adding more tools or upgrading the model. It was rewriting the tool descriptions. The team changed track_shipment to: "USE WHEN the customer asks about delivery status, shipping progress, or 'where is my order?' Returns real-time carrier tracking with current location and estimated delivery date." Tool selection accuracy jumped from 78% to 97%. Zero implementation changes. Just better words.

That is the lesson of this post in one paragraph: the description is the product.

The Core Idea

When you add a tool definition to the context window, you are not just giving the model a capability. You are changing how it thinks.

This is the non-obvious truth about the Equipment layer in the seven-letter framework from The CONTEXT Stack. Tools do not sit passively in the context waiting to be called. Their descriptions — names, parameter schemas, usage guidelines — become part of the information the model processes before generating any response. A model with access to a calculator approaches maths differently than one without. A model with access to a database lookup reasons differently about facts than one that has to rely on its training data. A model with a send_email tool starts considering communication actions it would not otherwise imagine.

Tool descriptions are context. They compete for attention in the context window alongside the system prompt, the retrieved knowledge, the conversation memory, and the user's message. At roughly 100-200 tokens per tool, 40 tools consume 4,000-8,000 tokens of context budget before a single user query is processed. At 100 tools, you are spending 10,000-20,000 tokens — potentially 20% of a 100,000-token window — just on tool definitions.

This creates a paradox. More tools means more capability. True. More tools also means more context consumed by tool definitions, less context available for knowledge and memory, and more cognitive load on the model when choosing which tool to call. Also true. The two pull in opposite directions. The PM has to navigate the trade-off consciously.

The numbers bear this out. With 10 well-described tools, models select the correct tool 95%+ of the time. With 40+ tools (even well-described ones), selection accuracy drops to 75-80%. With 100+ tools, models spend more reasoning effort on choosing the tool than on executing the task.

The implication: tool design is product design. The PM decides not just what tools the system can use, but which tools are loaded for which scenarios. And the tool description — the text the model reads when deciding whether to use a tool — is a product artefact, not an engineering implementation detail.

Think of it like: a well-organised kitchen. A chef with 10 tools on the counter — knife, pan, spatula, whisk, measuring cup, cutting board, tongs, peeler, grater, thermometer — works efficiently. Every tool is visible, reachable, and the chef knows exactly when to use each one. A chef with 40 tools on the same counter — including a blowtorch, a mandoline, a fish scaler, and a melon baller — spends more time scanning the counter than cooking. The counter is the context window. Every tool on it costs attention.

Three principles make tool design effective in production.

Principle 1: Behavioural descriptions, not API documentation. Most tool descriptions read like engineering documentation: get_portfolio(client_id: string) → Returns portfolio holdings as JSON array with ticker, shares, and current_value. This tells the model what the tool returns. It does not tell the model when to use it. Effective descriptions tell the model when and when not to use the tool — USE WHEN and DO NOT USE WHEN clauses written in the language of user intent, not API syntax. A 50-token cost to remove a 25% selection-error rate is a trade every product should make.

Principle 2: Dynamic loading, not static availability. Instead of loading all 40 tools for every query, classify the user's intent first and load only the relevant tools. A shipping question loads four tools, ~600 tokens. A billing question loads four different tools, ~600 tokens. Dynamic loading saves roughly 85% of the token budget that would have been spent on tool definitions, and improves selection accuracy from 78% to 97% — because the model is choosing from four relevant options instead of forty mixed ones.

The trade-off: dynamic loading requires an intent classifier before the tools are loaded. (An intent classifier — a small, cheap model that reads the user's message and labels it with a category like "shipping" or "billing." It runs first; the labels decide which tools the main model gets to see.) If the classifier mis-routes, the wrong tools get loaded and the model cannot help. The classifier becomes a critical first stage.

Principle 3: Read versus write classification. Tools that READ data have a different risk profile from tools that WRITE data. A read tool called incorrectly wastes a few tokens. A write tool called incorrectly takes an action the user did not request. Production systems classify accordingly: Read tools auto-execute. Write tools (reversible) execute with notification. Write tools (irreversible) require user confirmation before execution. Get this wrong and the AI does something the user did not authorise — once. The user never trusts it again.

Where This Hits in Production

MCP as the emerging standard. MCP (Model Context Protocol — an open standard developed by Anthropic for how AI models talk to external tools) is becoming the dominant interface for connecting AI models to external systems. With over 97 million monthly downloads as of 2026, MCP is to AI tools what USB was to computer peripherals. The plumbing got easier. The discipline did not — MCP tool descriptions still consume context tokens, and the quality of those descriptions still determines selection accuracy.

The tool token budget. Inside the context budget from The Context Window, tools compete with every other layer. A typical allocation: Constitution 3,500 tokens (fixed), Knowledge 8,000 (dynamic), Memory 3,000, Tools 2,500 (~10-12 tools), User message 500, Buffer 2,500. At 2,500 tokens for tools, you can afford 10-12 well-described tools per query. Need 40? You need dynamic loading. Need 100? You need a routing layer that selects 5-10 before the model sees any of them.

Tool errors cascade. When a tool fails — timeout, API error, malformed response — the error becomes part of the context (the eXecution layer in the framework). The model has to reason about the error and decide what to do next. If error handling is not designed into the tool description and the Constitution, the model may hallucinate a result, retry indefinitely, or give a confusing error message. Tool error handling is as important as tool success handling — and it is the failure mode most teams skip until production exposes it.

Connecting the Dots

Tools are the bridge between context engineering (Level 1) and full agentic systems (Level 3). At Level 1, the PM selects which tools the model can use. At Level 3, the agent selects its own tools, calls them in sequences the PM did not design, and reasons about the results to decide what to do next. The tool definitions become the agent's action space.

The autonomy connection. The tool set IS the autonomy boundary. An agent with access to read_database and draft_email can look things up and compose messages. Add send_email and the agent can take action in the world. Add delete_database_record and the agent can cause irreversible harm. Each tool you add expands the agent's capability AND its risk surface in equal measure. The full autonomy framing lives in Spectrum of Agency.

The eval connection. Evaluating Agents introduces tool correctness as one of the metric families an agentic eval has to track. Did the model select the right tool? Did it pass the right parameters? Argument correctness is a separate dimension from tool selection. Both have to be measured, separately. Otherwise the team thinks tools are fine and chases other ghosts.

Tool economics. Every tool call costs money. A model that makes three unnecessary tool calls before finding the right one costs three to four times more than one that selects correctly on the first try. Tool selection accuracy is a cost metric, not just a quality metric.

Remember This

1. Tool descriptions change the model's reasoning before any tool call happens. They are context that shapes behaviour — not passive capabilities waiting to be invoked. Write descriptions in user-intent language (USE WHEN, DO NOT USE WHEN), not API documentation language.

2. 10 well-described tools beat 40 poorly-described ones. Selection accuracy drops from 95%+ to 75-80% as tool count rises. Dynamic loading — intent classification, then load the relevant tools — solves this: 85% fewer tool tokens, 97% selection accuracy.

3. Tool design is product design. The tool set defines what the AI can do in the world. Each tool you add expands both capability and risk surface. Curate the minimum set that serves users — and treat tool count as a product metric on the dashboard.

In Practice — The Tool Audit

Here is what tool management looks like when treated as a product discipline. Consider a B2B SaaS platform whose AI assistant helps sales teams manage their pipeline. Over eight months, the team has connected 34 tools. Selection accuracy has drifted to 76%. The team runs an audit — mapping every tool against usage, accuracy, and token cost.

The restructuring keeps a core 6 tools always loaded (~1,120 tokens), dynamically loads tool packs by intent (Communication / Planning / Admin), and removes 3 rarely-used, low-accuracy tools. Total engineering effort: two days of description rewriting and intent-classification setup. Zero tool implementation changes. Quality up. Cost down. Latency down. User satisfaction up.

The improvement comes from three changes: fewer tools competing for attention (6 core vs 34), better descriptions written in user-intent language, and dynamic loading that matches the tool set to the user's actual need. The audit is the diagnostic. Dynamic loading is the lever. The description rewrite is the cheapest single quality improvement available in any AI product.