Naming Tools So a Model Picks the Right One

Names are short, high-salience tokens that the model has seen millions of times in tool-calling training data. A good name behaves like a compressed instruction.

The strongest evidence here is a schema-alignment study rather than an opinion. Researchers at Seoul National University found that small language models fail at tool use largely through schema misalignment: given tools with unfamiliar naming conventions, models hallucinate plausible but nonexistent tool names that reflect naming patterns internalized during pretraining. Their fix, called PA-Tool, was to rename tool components to match pretraining conventions, with no retraining of the model at all. On the MetaTool and RoTBench benchmarks the rename produced improvements of up to 17 percent and cut schema misalignment errors by 80 percent (the PA-Tool paper, ACL version). A naming change, not an architecture change, moved the failure rate that far.

Four naming rules do most of that work.

Lead with a verb. search_tickets, create_refund, fetch_invoice describe an action. tickets, refunds, billing describe a domain. Verbs map cleanly onto the imperative form of user requests.

Make sibling names differ in the first word. If you expose get_order_status and get_order_status_v2, you have built a coin flip. Distinguish by verb and object: check_order_status versus fetch_order_history.

Avoid internal jargon and abbreviations. crm_lookup_v3 means nothing to a model that has not seen your internal wiki. find_customer_by_email means something immediately.

Keep names consistent across one server. Mixed conventions (stripe_charge, DoRefund, invoices.list) tell the model you have no scheme, and it guesses.

The last row is a common trap. Names that bundle several effects force the model to reason about side effects it cannot verify. One name, one verb, one outcome.

If you are wiring several models, including smaller ones, into one tool surface, testing candidate names against the model you actually deploy matters more than elegance. Quanta Inference exposes text, image, video, audio and embedding models through one OpenAI-compatible API key, which makes it practical to replay the same set of test prompts against more than one endpoint before you settle on a naming scheme.

A description has one job beyond describing: it must tell the model what this tool is not for. Most schema bugs come from descriptions that only enumerate capabilities, leaving adjacency to be guessed.

The PA-Tool finding above has a practical corollary. Models carry priors about how tool descriptions read, so descriptions that follow the patterns seen in training data are easier to route. Short declarative sentences with an explicit boundary beat adjectives.

Consider a booking agent with three tools. A first draft:

"description": "Manages hotel bookings, cancellations and modifications."

That single sentence invites the model to use it for every booking-adjacent request, including refunds it cannot perform. A paired version:

"description": "Create a new hotel reservation. Use when the user gives a hotel,
check-in and check-out date and wants a new booking.
Do not use to change or cancel an existing booking; use modify_booking or
cancel_booking instead."

Under the hood the two tools may call the same endpoint. The description is what separates them.

A few content rules are worth standardizing across a toolset:

• Open with the action, in plain English, not a noun phrase. "Create a new hotel reservation" beats "Hotel reservation creation utility."
• State when to use it, referencing the kind of user request it serves.
• State when not to use it, and name the alternative tool explicitly. This single sentence is the highest-yield edit in most schemas.
• Describe preconditions, such as required identifiers the user must supply first.
• Say what it returns, briefly, so the model knows whether follow-up calls are needed.
• Avoid marketing language and absolute words like "always" or "unlimited," which push the model toward over-triggering.

Note what is not on the list: JSON formatting detail. The structural schema already covers types. Repeat natural-language constraints only where the model should reason about them.

There is also a security dimension to how descriptions are written and read. OWASP documents MCP tool poisoning as an attack in which a malicious server exposes normal-looking tool names and descriptions, then returns responses carrying hidden instructions that land in the model's context and are treated as trusted (OWASP on MCP tool poisoning). The attack works because descriptions are reviewed once at connect time while responses are not. Your naming standard does not stop that, but a discipline of describing tools with explicit scope, plus a response-format contract, gives you a place to hang the runtime checks covered later.

Enums are where models make argument-level mistakes, and those mistakes are often harder to spot than wrong-tool calls because the request succeeds and returns a plausible answer for the wrong slice of data.

The rule: a label should be unambiguous when read alone, outside the tool description and outside the user's sentence. open and closed pass. 1 and 2 fail. pending is borderline because it means different things in ticket systems and in payment flows; pending_customer_reply does not.

Compare two ways to express the same filter on a support tool:

Three practices follow from the table.

Pad the space between labels. If two labels can describe the same request, a model will split between them unpredictably. high and urgent overlap; either drop one or write the boundary into a description.

Prefer self-describing words to codes. Codes require a lookup table, and models perform that lookup unreliably, especially when the same code appears in two tools with different meanings. The schema-matching literature makes the broader point: when systems must match schema elements using names and descriptions alone, both must carry the meaning on their face (LLM-Matcher).

Constrain output shape when possible. The same argument applies to the model's response, not just its input: enforcing a defined structure up front removes a whole class of parse failures downstream (Agenta's guide to structured outputs). A fixed schema for tool arguments and results is the preconditions; clean enum labels are what make the arguments readable.

One more habit worth adopting: derive enum labels from the wording your users actually type. If analytics shows people ask for "the last 30 days," not "month to date," label the option accordingly. Names are a matching surface, and matching improves when both sides use the same vocabulary.

Structural validation proves a tool call is well formed. It cannot prove the right tool was chosen. The gaps that survive validation are things like: a model calling get_order_status when it needed get_shipping_status, an enum value that is valid but semantically wrong, or a tool selected for an operation the user was never authorized to perform. These show up as plausible, wrong answers, which is why code review and unit tests rarely catch them.

Run this audit on any toolset before release and after any prompt or model change. Each item is a yes or no, and a single no is a field to rewrite, not a discussion.

Items 8 to 10 come straight from the defensive guidance around tool servers: constrain response format, isolate privileged tools, enforce restrictions server-side and require explicit confirmation for sensitive operations (OWASP). They are part of a naming audit because a well-named tool that is over-privileged is still a liability.

The test-prompt set in item 6 is where the audit earns its keep. Write them as one small file so they can run as a regression suite:

CASES = [
    # (user prompt, expected tool, must_not_be)
    ("Show my last three orders", "recent_orders", "search_tickets"),
    ("Refund order 1042", "refund_order", "modify_booking"),
    ("Where is my package", "get_shipping_status", "check_order_status"),
]

Run every case against each model you deploy and record mismatches. A failed case points at exactly one of three fields. If the correct tool never fired, the name or the description's "when to use" sentence is weak. If two tools split the votes, their descriptions lack a boundary or their enums overlap. If the tool fired but the argument is wrong, the enum labels are doing too little work.

A support agent has three poorly named tools, and the mismatch rate on the queue is high. First pass, the schema as received:

[
  {"name": "tickets", "description": "Ticket utility."},
  {"name": "handleTicket", "description": "Handles tickets."},
  {"name": "ticket_update", "description": "Updates a ticket status."}
]

Every prompt about tickets is a coin flip. The names share a stem, two descriptions are circular, and no description states a boundary. The rewrite separates on verb and object, and each description carries a "do not use" line:

[
  {"name": "search_tickets",
   "description": "Find tickets by status or priority. Use when the user wants a list of matching tickets. Do not use to change a ticket; use update_ticket_status instead.",
   "parameters": {"type": "object", "properties": {
     "status": {"type": "string", "enum": ["awaiting_agent","awaiting_customer","resolved","archived"]},
     "priority": {"type": "string", "enum": ["low","medium","high","urgent"]}}}},
  {"name": "update_ticket_status",
   "description": "Change the status of one existing ticket, identified by its numeric id. Do not use to list tickets or to add comments.",
   "parameters": {"type": "object", "properties": {
     "ticket_id": {"type": "integer"},
     "status": {"type": "string", "enum": ["awaiting_agent","awaiting_customer","resolved","archived"]}},
    "required": ["ticket_id","status"]}},
  {"name": "add_ticket_comment",
   "description": "Attach a written comment to one existing ticket. Use when the user wants to leave a note or reply. Do not use to change status.",
   "parameters": {"type": "object", "properties": {
     "ticket_id": {"type": "integer"},
     "body": {"type": "string"}},
    "required": ["ticket_id","body"]}}
]

Nothing in the JSON structure changed except the enum breadth. The fix is entirely in the prose. A reader can verify the improvement without a benchmark: for the prompt "close ticket 1042," only update_ticket_status contains both the action and the identifier, and its description says which tool to use instead when the user wants a list.

When a team is maintaining a dozen such toolsets across business lines, the manual audit does not scale linearly. Putting a named domain expert on the tool surface, with the skill library behind it, is one way to keep the vocabulary consistent as tools are added. Quanta Experts reads the local context, does the work and hands back a finished deliverable, which fits a review pass over schemas and test prompts.

The same naming rules apply whether tools are defined inline for a function-calling API or discovered at runtime from an MCP server, but the failure modes differ.

With inline function calling you own the whole surface: names, descriptions, enums, execution and the dispatch loop. That control makes a naming audit straightforward, though it also means you rewrite tool definitions per provider if you switch vendors (Prefect). With MCP, a server publishes its tools and a client surfaces them, so your leverage is split between the server author and the host. The protocol's conventions put human-readable identity in title and a short functional summary in description, alongside the machine-facing name, and that split is deliberate (MCP prompts reference). Clients increasingly use the descriptive fields for discovery and ranking, which means a server that leaves description thin underperforms however good its endpoint is.

The time-to-value comparison makes the choice concrete. Writing an API integration takes days of auth setup and field mapping; connecting an MCP server takes minutes, and the assistant assembles the calls per question instead of running a fixed script (Mitiga's MCP vs API breakdown). For exploration, MCP wins. For a deterministic nightly job, the API wins. Neither is a substitute for naming discipline, because both end up presenting a text description to a model.

The practical consequence for schema authors is a decision rule about where to invest. If the tool surface is small and stable, spend the time on descriptions once and add a regression prompt set. If the surface is large or changes often, invest in the names and the enum vocabulary, because those are the parts that survive a rewrite of the wrapper. Teams that keep a skill per domain, installed into a coding agent or applied by a named expert, get this for the cost of maintaining the skill text rather than the whole integration. Quanta Skills is the library that library runs on.