If the schema is machine-readable, why do serious builders still write tool descriptions like warning labels?

This is an embarrassing builder question because it sounds like copywriting at the exact moment everyone wants to talk about reasoning. The stack finally has local models, MCP tools, approvals, and an inspector window. Then somebody asks the low status thing: why is this tool named that, and why does its description read like a safety sticker? Demo culture hears polish work. Serious operators hear the first trust contract.

The thesis:

Names, titles, and descriptions are not decorative metadata. They are the shared surface where the model chooses, the operator approves, and the next human understands the side effect. The schema matters, but it starts helping after the tool is selected.

The schema begins after the tool was chosen

OpenAI's current function-calling guide says to write clear function names, detailed parameter descriptions, and to make the definition pass the intern test. That is not ornamental advice. It is a recognition that a model chooses tools through language before it ever validates a JSON payload.

The same point is even more explicit in OpenAI's current Define tools guide. It says descriptions are used for selection, should describe user intent rather than implementation, should distinguish similar tools, and should call out limits or prerequisites. If the tool text only restates the name or hides behind internal jargon, the model is choosing with worse coordinates than the human.

OpenAI's current plugin guidelines close the loop from model selection to user trust: tool names should be human-readable and descriptive, descriptions must match behavior, and hidden side effects are not acceptable. That is why dependable tool text feels slightly legalistic. It is supposed to survive inspection.

Question Demo answer Dependable answer

Why bother with wording? The model can infer the rest. The model chooses through language before the schema constrains anything.

Who is the audience? Mostly the model. The model, the approving operator, and the next human reviewer.

What must be visible? The happy-path capability. Purpose, lane, prerequisites, and whether the action reaches outside the current environment.

Current MCP docs keep the human layer inside the contract

The latest MCP tools specification defines tools as named actions with metadata and schemas, then keeps the user in the loop: clients should show which tools are exposed, show visual indicators when tools are invoked, and present confirmation prompts for operations. That means the tool contract is not only a machine interface. It is a UI surface.

The current MCP schema reference makes the split even clearer. It says title is intended for UI and end-user contexts and should be easy for people unfamiliar with domain jargon to understand. It also calls description a human-readable hint that helps clients improve the model's understanding of the tool. The protocol is telling builders to care about prose on purpose.

That is the gap between demo magic and dependable tools. Demo magic wants names that sound powerful. Dependable tools want language that survives refusal, approval, and handoff.

The inspector already turns weak tool copy into a public bug

The current MCP Inspector web client docs say that when you select a tool, you see its description, its input schema rendered as a form, and its annotations. That is a practical receipt. The first debugger a builder reaches for already exposes the same thing the model and the user see. If a tool needs a live spoken explanation to be safe, the problem is not the inspector. The problem is the tool contract.

This is why good tool wording often sounds like a warning label: say what it does, say when to use it, say what lane it belongs to, and say what it will touch. The boring sentence is part of the safety model.

Chopshopr's own tool lanes get better when the copy is blunt

Chopshopr's public README tool inventory already leans in this direction. The local LLM lane separates normal inference (local_generate_default) from explicit cross-model calls (local_generate), diagnostics (local_health and local_list_models), operator-only lifecycle actions (local_start_server and local_stop_server), and persistence utilities (local_wait).

The source files keep the same posture. In src/local-llm/tools.js, descriptions explicitly say which tools are canonical, which are operator tools, and which are utilities. In src/nemoclaw/tools.js, the host-side tools are named nemoclaw_doctor, nemoclaw_run, and openshell_run; their descriptions say bounded host-side command, status/logs, and sandbox inspection. That is not accidental tone. It keeps the default lane, the authority lane, and the debugging lane legible.

# Boring names make the lane obvious.
local_generate_default  # normal inference on the configured default model
local_health            # connectivity plus default-model availability
local_wait              # stay inside the same MCP run while local work continues
nemoclaw_doctor         # host tooling readiness
nemoclaw_run            # bounded host-side NemoClaw command
openshell_run           # bounded host-side OpenShell command

Name the lane

Tell the model whether this is the default path, a diagnostic path, or an operator-only control.

Name the surface

Say whether the tool touches the local backend, host CLI, sandbox, account, or public route.

Name the side effect

If it writes, sends, deploys, or reaches the open world, the definition should admit that directly.

Name the fallback

Good wording makes refusal, retry, and handoff possible without folklore from the original builder.

Write tool copy that survives three audiences

The model: describe the job and the trigger so selection is cheap and accurate.
The operator: say the side effect, prerequisite, or approval seam before the tool runs.
The next human: name the system touched so a reviewer can reconstruct what happened later.
Avoid vanity: do not make the tool sound smarter, broader, or safer than it is.
Prefer boring over clever: if a name feels slightly over-literal, that is usually a good sign.

The sharp insight is not that schemas are unimportant. It is that schemas are only one layer of the contract. Reliable local-first agents, MCP tools, bounded host ops, and public proof surfaces all get adopted faster when the first sentence above the action is plain enough to survive both machine choice and human suspicion.