Tool descriptions are part of your agent's control plane
Why tool names, descriptions, schemas, and availability often matter more than tool count in LangChain agents, with a practical design and evaluation method.

@tool
def find_customer(query: str) -> list[Customer]:
"""Find a customer."""
That is valid LangChain code. It is also an underspecified interface.
Does query accept an email address, a CRM ID, a company name, or all three? Does the function return one record or a fuzzy match list? Should the agent call it before creating a deal? Can it expose inactive customers? The Python implementation may know the answers. The model does not, unless the tool contract tells it.
For an agent, a tool description is not documentation around the system. It is part of the input that shapes the next action. The name, description, JSON schema, argument descriptions, and currently available alternatives jointly define a probabilistic decision boundary. A weak interface makes a capable model look unreliable. A strong interface does not make an unreliable architecture safe.
This distinction matters when teams respond to a missed tool call by adding another tool. More capability can make an agent worse if it enlarges the candidate set without giving the model a clean way to distinguish the options.
Tool selection is a classification and grounding problem
At inference time, the model receives a request and a representation of the available functions. It must decide whether to call anything, rank candidate functions, construct valid arguments, interpret the returned observation, and decide what to do next. Providers may serialize this differently, but the reasoning burden remains.
LangChain's tools documentation describes the basic contract plainly. A tool is a callable with well-defined inputs and outputs. The model decides whether to invoke it and which arguments to provide. With @tool, the function docstring becomes the description and type hints define the input schema.
That convenience makes tool authorship look like ordinary API documentation. It is closer to prompt engineering with an execution boundary. The model reads words such as "search", "lookup", "authoritative", "latest", "only", and "never" as evidence when it chooses a function. It also reads every competing tool at the same time.
The 2025 EMNLP paper "Tool Preferences in Agentic LLMs are Unreliable" makes the uncomfortable part measurable. In controlled comparisons with competing tools that shared an interface, edits to descriptions could cause a tool to receive more than ten times as much usage from GPT-4.1 and Qwen2.5-7B. That result is about preference and call frequency, not a claim that a wording trick creates ten times better task completion. It does show that natural-language interfaces can redirect agent behavior without changing the underlying capability.
The practical implication is not to game descriptions. It is to treat them as a versioned, evaluated part of the agent specification.
More detail helps only when it removes a decision
The difference between a useful description and a long description is whether it rules out a plausible wrong call.
Consider an order support agent. The following definitions give the model almost no basis for a reliable choice.
from langchain.tools import tool
@tool
def search_orders(query: str) -> list[dict]:
"""Search orders."""
...
@tool
def get_order(order: str) -> dict:
"""Get order details."""
...
The tool names overlap. The parameter names differ without communicating meaning. Neither function states the return cardinality or a condition for use. A user writing "Where is order 4182?" might trigger either one. If the backend interprets search_orders("4182") as full-text search, it may work until a future record, tenant boundary, or pagination rule makes it fail.
This version establishes a decision boundary.
from typing import Literal
from pydantic import BaseModel, Field
from langchain.tools import tool
class OrderSearchInput(BaseModel):
query: str = Field(
description="Customer-visible text, email address, product name, or date phrase. "
"Do not pass an order ID when an exact order lookup is required."
)
status: Literal["open", "fulfilled", "cancelled"] | None = Field(
default=None,
description="Optional lifecycle filter. Omit when the user did not state a status."
)
@tool(args_schema=OrderSearchInput)
def search_orders(query: str, status: str | None = None) -> list[dict]:
"""Find zero or more orders when the user gives incomplete or descriptive information.
Use this to identify a candidate order by customer email, product, date, or status.
Do not use it when the request contains one exact order ID. This tool never changes an order.
"""
...
@tool
def lookup_order(order_id: str) -> dict:
"""Read one order by its exact immutable order ID, such as ORD-4182.
Use this after the user provides an exact order ID or after search_orders returns a
single confirmed candidate. Do not use it for name, email, or free-text searches.
This tool is read-only and returns the current fulfillment state and line items.
"""
...
The second version gives the model five useful facts. It states the job, required evidence, input interpretation, exclusions, and side-effect boundary. Field-level descriptions matter because the model has to select a tool and populate its schema. LangChain supports both Pydantic and JSON Schema args_schema definitions for this purpose. It also supports parse_docstring=True when argument documentation should be captured from a structured docstring.
The exclusions do real work here. "Do not use it for name, email, or free-text searches" is more useful than another sentence saying lookup_order gets order details. Constraints reduce the probability mass of an attractive but invalid option.
There is a limit. A description that includes every backend fact becomes prompt clutter. A model may miss the one condition that mattered, use a spurious phrase as a selection signal, or spend more context processing the registry than planning the task. A tool contract should be short enough to scan and precise enough to reject its nearest competitors.
Why overlapping tools fail in production
Semantic overlap is common because product teams model systems around backend ownership while users describe work in business terms. A CRM can expose search_contacts, find_account, get_customer, and lookup_person. Each function may be defensible in isolation. Together, they create several questions the model cannot answer from the user request alone.
Which one is authoritative? Which accepts a stable identifier? Which one returns a list? Which can be called for a prospect rather than a customer? Which is permitted for the current tenant? A description that says "searches CRM records" answers none of them.
This is why renaming tools is sometimes a higher-leverage change than adding a capability. get_record is technically generic. read_verified_billing_profile carries role, scope, and authority. The latter can still be too broad, but it helps the model and the engineer reviewing a trace reason about the intended path.
The MetaTool benchmark tested both whether models should use a tool and which tool they should choose. Its ToolE dataset covers about 21,000 queries across 390 tools. One of its more useful findings for practitioners is that description rewriting is model-dependent. A rewrite produced by GPT-4 improved some downstream models and degraded others. There is no universal "better wording" independent of the model, tool set, and task distribution.
That finding rules out a tempting process. Do not ask a strong model to rewrite the registry, accept the prose because it sounds clearer, then treat the improvement as proven. Evaluate the exact model and registry that will serve production traffic.
Schema design changes reliability after selection
An agent can choose the correct tool and still fail by emitting the wrong arguments. Tool names and descriptions determine candidate selection. The schema grounds an abstract request into an executable call.
Use types for closed sets. Use field descriptions for meaning that types cannot express. Use explicit optionality so the model does not invent a value just to fill a required field. Avoid generic argument names such as value, data, and query when the value has a domain identity.
class RefundInput(BaseModel):
order_id: str = Field(
description="Exact immutable order ID. Never pass an email, customer ID, or payment ID."
)
amount_cents: int = Field(
gt=0,
description="Refund amount in minor currency units. Must not exceed the refundable balance returned by lookup_order."
)
reason: Literal["duplicate", "damaged", "not_received", "other"] = Field(
description="Customer-stated refund reason. Use 'other' only when none of the listed reasons apply."
)
The schema should not be the only validation layer. Pydantic can validate an integer and an enum. It cannot prove that a refund amount is authorized for the current account without live state. The tool implementation must verify that rule. Middleware or the graph should ensure that the agent cannot execute the action without an approval when policy requires one.
Treat returned data as part of the contract too. A vague response forces the model to infer which fields matter. A structured response with a status, stable IDs, an authority marker, and an error category gives the next model step a reliable observation. For side-effecting tools, return the idempotency key or action ID so the agent can recover without repeating the action.
The registry itself is a prompt
An agent does not select a tool from a vacuum. It selects from the set that is visible at that moment. Adding tools changes the decision problem even if the new tools are never called.
The ToolRet benchmark makes the scale problem concrete. "Retrieval Models Aren't Tool-Savvy" evaluates 7,600 retrieval tasks against a corpus of 43,000 tools. It reports that models strong on conventional information retrieval still perform poorly on tool retrieval, and that weak retrieval lowers the pass rate of the downstream tool-using LLM.
This is an important correction to a common architecture diagram. Tool retrieval does not simply make a large registry manageable. It inserts another model or ranking component that can hide the necessary tool. The agent cannot call a tool it never sees.
The trade-off has three parts.
-
Exposing everything maximizes availability but raises context cost and semantic competition. It works for a small, coherent set of tools.
-
Selecting a small subset reduces prompt size and can make the main agent more accurate. It risks false negatives in the selector.
-
Retrieving on demand scales to large or changing registries. It requires a retrieval evaluation that measures whether needed tools survive to the final decision step.
No fixed threshold is universal, but LangChain documents LLMToolSelectorMiddleware for cases with many tools, particularly ten or more. The middleware asks a model with structured output to select relevant tools before the main model runs. max_tools caps the selected set and always_include keeps mandatory tools visible without consuming that cap.
from langchain.agents import create_agent
from langchain.agents.middleware import LLMToolSelectorMiddleware
agent = create_agent(
model="openai:gpt-5",
tools=all_tools,
middleware=[
LLMToolSelectorMiddleware(
model="openai:gpt-5-mini",
max_tools=4,
always_include=["get_current_user", "request_human_approval"],
),
],
)
This is not a free accuracy upgrade. The selector sees the same kinds of names and descriptions that confused the main agent. It moves the ambiguity one stage earlier. It can still be worth it because the selector has a narrower task, a bounded output schema, and a cheaper model. The system now needs selector recall, selected-set size, end-to-end task success, and cost per successful run as separate metrics.
For deterministic context such as tenant, role, region, product, or workflow state, use code to filter tools before asking a model. LangChain's custom AgentMiddleware can override the tools supplied to a model call. That makes access control and known routing rules executable rather than advisory prose.
from collections.abc import Callable
from langchain.agents.middleware import AgentMiddleware, ModelRequest, ModelResponse
class TenantToolBoundary(AgentMiddleware):
def wrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], ModelResponse],
) -> ModelResponse:
tenant_id = request.runtime.context["tenant_id"]
allowed = [tool for tool in request.tools if tenant_id in tool.metadata["tenants"]]
return handler(request.override(tools=allowed))
The right division of labor is simple. Code should apply facts known by the runtime. The model should resolve semantic ambiguity that remains after those facts are applied.
Descriptions cannot fix an architecture that exposes the wrong action
Some reliability defects are category errors. They should not be fixed with a better verb in a docstring.
If send_payment is visible before identity verification, an instruction saying "only use after verification" is a suggestion. If a tool combines search and mutation, no description can make its side effects easy to audit. If a tool accepts a free-form SQL string, an accurate description does not establish a safe query boundary. If tools have identical behavior but separate branding, the model should not be expected to discover organizational ownership from prose.
Use architectural changes when any of these conditions apply.
-
The correct tool depends on deterministic state such as role, tenant, or approval status.
-
Tool families grow beyond the context and evaluation budget of a flat registry.
-
A wrong call has a material side effect, high cost, or a permission boundary.
-
The task needs a multi-step plan where later tools depend on earlier observations.
-
The same semantic ambiguity repeats in traces after the tool contracts have been tightened.
In those cases, introduce a state machine, a deterministic router, retrieval with coverage evaluation, explicit approval middleware, or a domain-specific subagent. Better descriptions still matter inside each smaller interface. They are no longer carrying the whole safety argument.
Evaluate tool interfaces as behavior, not prose
A code review can catch a missing field description. It cannot tell you whether the serving model will choose the correct function among near-duplicates. Treat the tool registry as a testable artifact.
Start with a compact suite of real requests. For each case, record the required tool or acceptable set, forbidden tools, expected arguments, relevant runtime state, and whether the final answer is correct. Include contrast pairs that differ by one decisive fact.
{
"case_id": "refund-approval-014",
"request": "Refund ORD-4182 for 24.99 EUR",
"runtime": {"verified": true, "approval": false},
"expected_tools": ["lookup_order", "request_human_approval"],
"forbidden_tools": ["issue_refund"],
"expected_argument_constraints": {
"lookup_order.order_id": "ORD-4182"
}
}
Measure more than final-answer accuracy.
| Metric | What it catches |
|---|---|
| Tool selection accuracy | The required tool was selected when visible. |
| Forbidden-tool rate | A tool crossed a policy or scope boundary. |
| Argument validity | The emitted call conforms to schema and domain constraints. |
| Selector recall at k | A required tool survived preselection or retrieval. |
| Trajectory efficiency | The agent avoided redundant calls and irrelevant detours. |
| Task success | The user received a correct, authorized result. |
Run the suite whenever a description, schema, model, selector, or registry membership changes. Those are behavior changes. A registry that becomes more descriptive can regress because it changes how nearby tools compete for attention.
LangChain middleware gives this work a natural place to live. wrap_model_call can control the visible registry. wrap_tool_call can validate, log, retry, or reject an execution. Tool-call limits contain loops. Human-in-the-loop middleware can stop an action before it becomes an irreversible side effect. Pair the controls with traces so a failure can be assigned to selection, argument grounding, execution, or observation handling.
A practical design sequence
When an agent selects the wrong tool, do not start by adding examples to the system prompt. Inspect the trace and identify the failed stage.
- Check availability. Was the needed tool present and allowed for this runtime state?
- Check semantic separation. Could an engineer choose between the candidate descriptions without knowing the implementation?
- Check schema grounding. Did the selected tool make its inputs and exclusions unambiguous?
- Check execution policy. Was an unsafe action blocked independently of the model's reasoning?
- Check the observation. Did the tool return enough structured evidence for the next step?
- Add the failure to a regression suite before rewriting anything.
Often the fix is a concise description that says what the tool is for and what it is not for. Sometimes it is a better argument name or a stricter enum. At registry scale, the fix is usually progressive disclosure plus an evaluation loop. At a security boundary, the fix is code.
The useful rule is not "better descriptions beat more tools." Better descriptions improve the agent only when the capability is already appropriate, visible, and enforceable. Once tool choice depends on dynamic state or the registry becomes large, the interface needs architecture around it.
LangChain makes that progression practical. Start with explicit @tool contracts and typed schemas. Use middleware to apply known runtime constraints. Add LLMToolSelectorMiddleware when a flat tool list has become a prompt and cost problem. Then evaluate the full path. The result is not a tool list that reads well to humans. It is a control surface that behaves predictably under the requests your users actually send.
Sources
- Faghih et al., Tool Preferences in Agentic LLMs are Unreliable, EMNLP 2025.
- Huang et al., MetaTool Benchmark for Large Language Models, ICLR 2024.
- Shi et al., Retrieval Models Aren't Tool-Savvy, Findings of ACL 2025.
- LangChain, Tools, prebuilt middleware, and custom middleware.

