MCP and tools
Tool schemas Claude actually calls
Claude skips, mis-fills, or over-calls tools when the schema is written for OpenAPI completeness instead of for a model. Here is how we design MCP tools that get used correctly.
May 4, 2026/5 min read/Claude Certified Engineers
Claude does not read your internal wiki. It reads the tool schema you hand it: names, descriptions, required fields, and the error strings your MCP server returns. If those are written like an OpenAPI dump of a 200-endpoint CRM, Claude will guess. Guessing looks fluent. It is also how you refund the wrong invoice.
Model Context Protocol is the right transport. It is not a design. The design is which verbs Claude is allowed to use, how small those verbs are, and what happens when a call is illegal. That is the work we do on MCP and Tool Integration engagements, and it is the part most "we connected Claude to Salesforce" demos skip.
Write verbs, not a mirror of the API
A tool is a job. create_salesforce_opportunity is a job. salesforce_request with a freeform method, path, and body is a remote shell. Claude will use a remote shell. Your security team will not enjoy the traces.
Collapse the surface until each tool has one outcome:
- Fetch a record by a stable id.
- Search with two or three filters you actually have indexes for.
- Create or update a documented object, with required fields that match the downstream system.
- Handoff to a human when the action is irreversible.
If a human engineer would not give a new hire curl * against production, do not give it to Claude.
| Smell | What Claude does | Fix |
|---|---|---|
| One mega-tool wrapping REST | Invents paths and fields | Split into 6-12 named verbs |
| Optional everything | Omits the one field the API needs | Mark required fields required |
| Description restates the name | Under-uses the tool | Describe when to call it, and when not to |
| 40 tools on one agent | Picks a cousin of the right call | Split agents or hide tools by step |
| Errors as HTML or stack traces | Retries the same bad payload | Return a short, schema-shaped error |
Aim for a dozen tools, not a hundred. Retrieval can sit behind one search_docs with a corpus id. Do not explode that into a tool per folder.
Describe when to call, not what the function is
The description field is a policy document. Write it for the model:
Create a Salesforce opportunity. Call this after account_id and amount are known. Do not call it to take notes or to log a call. Never invent an account_id.
Put the negative instructions in the schema. Claude is much better at not calling a tool that said "never invent an account_id" than at inferring that from a 12-page system prompt.
Field descriptions need the same treatment. account_id should say Salesforce Account Id, 18-character, starting with 001. Never pass a name or a URL. If you accept both a name and an id, you will get names, and your resolver will hit the wrong record.
Enums beat free text wherever the downstream system has a closed set. Stage names, currencies, ticket priorities. If the API will 400 on "in progress" vs "In Progress", the schema should not pretend both are fine.
Make the server boring and strict
An MCP server should be a thin, permissioned adapter:
- Authenticate as a constrained service account, not as an admin user copied from a demo.
- Validate arguments against the same JSON Schema Claude saw. Do not "helpfully" coerce.
- Call one downstream method.
- Return a small JSON object Claude can read in one glance:
ok,id,summary,error_code. - Log the call with the requesting principal, the tool name, and the record ids. Redact payloads that can contain PII.
If validation fails, say so in a structured way: error_code: missing_account_id. Claude can recover from that. It cannot recover from a 14-line Java stack trace, and it will retry.
Idempotency keys belong on create and update tools. Agents retry. Double-charged refunds are a schema problem, not a model problem.
Scope tools per environment. The staging server can have delete_opportunity. Production should not, or it should require a change_ticket_id that only a human can mint.
Confirm the contract with traces, not with a happy-path chat
Once the server runs, do not "try a few prompts." Run the same eval harness you use for the rest of the agent, with cases that exist to break tools:
- Missing required fields.
- Valid fields that point at the wrong object type.
- Injection in a search string.
- A user asking for an export the tool must refuse.
- A retry after a 409 conflict.
Score tool choice and argument validity separately from the final English. An agent can apologize beautifully while calling refund on the wrong id.
This is also where Architect-level review earns its keep. Someone has to ask: should Claude be allowed to take this action at all, or should the tool stop at a draft plus a review queue? Irreversible money movement, PHI access, and privilege-sensitive legal files belong behind a human checkpoint. MCP makes that easy to skip. That is why we do not skip it.
If your current integration is a single catch-all tool, the next step is not a bigger prompt. It is a smaller surface, a stricter server, and a suite that fails when Claude invents a field. That is the integration we ship. If you want it on your stack, book a 15-minute discussion.
Questions
- Why does Claude ignore or mis-fill MCP tools?
- Most schemas are written as OpenAPI dumps with optional fields and vague descriptions. Claude then guesses. Named verbs, required fields, and negative instructions in the description fix most of it.
- How many MCP tools should one Claude agent have?
- Aim for a dozen, not a hundred. If you need more, split agents or hide tools by step. Forty tools on one agent makes Claude pick a cousin of the right call.
- Should irreversible actions be MCP tools?
- Only behind a human checkpoint. Refunds, PHI access, and privilege-sensitive files should stop at a draft plus a review queue, not execute on the first call.
Sources