How to build an MCP agents actually understand

Plenty of teams have connected an agent to an MCP server expecting magic and got something clumsy instead. The agent calls the wrong tool, asks for an ID it can't know, or gives up. The data was there. The server just wasn't built the way an agent thinks.

The best-loved MCP servers have one thing in common: they describe the business the way a person would, not the way the database stores it. Here's what that means in practice.

1. Use the identifiers people use

An agent knows a VIN. It doesn't know your internal vehicle_id of 88213. A customer knows their phone number, not your contact key.

• Do: get_vehicle by vin. Look up a customer by email or phone.
• Don't: require an internal ID the agent has to discover through three other calls first.

If you need internal IDs, accept the human one and resolve it yourself.

2. Call things what the industry calls them

make, model, trim, odometer, repair_order, stock_number. Not mk, mdl_cd or field_17. An agent has read the whole internet. It knows what a repair order is. Use the word.

3. Write descriptions for a smart new hire

Every tool and every field gets a plain-English description: what it does, when to use it, what comes back. The description is the documentation the agent reads before every call.

• Weak: "Gets inventory."
• Strong: "Search vehicles currently in stock at this dealership. Filter by make, model, year, price and new or used. Returns up to 50 vehicles with VIN, price and photos."

4. Fewer, sharper tools

Twelve tools that each do one clear job beat sixty that overlap. If two tools differ only by a flag, merge them. If one tool does five things, split it.

5. Return what the next step needs

When an agent books a service appointment, return the confirmed time, the advisor and what to bring, so it can tell the customer without another call. Think about the conversation, not just the record.

6. Say what went wrong in words

"No open slots on Saturday. The nearest openings are Friday 4pm and Monday 8am" lets the agent recover. error 422 doesn't.

7. Money and time, unambiguous

Prices as whole cents plus a currency code, never a float. Times with a timezone offset. Agents do arithmetic on these, so leave nothing to guess.

8. Never trust the agent with scope

Which dealership's data a caller can see is decided by its credentials, enforced on your server. Never by a parameter the agent fills in and never by an instruction in a prompt.

Want a head start?

The docs include recommended tool names and data shapes for the main dealership areas, built on exactly these rules. Use them where they fit, and tell us where they don't.