7 MCP Tool-Schema Mistakes That Make AI Agents Less Reliable

AI agents can only use tools as reliably as those tools are described.

That’s why I built ToolReady AI—a free tool that reviews MCP and AI-agent tool schemas, identifies reliability problems, and recommends specific fixes.

A function might work perfectly when a developer calls it directly, yet still fail when an agent has to decide when to call it, which arguments to provide, and what values are safe. In many cases, the problem is not the underlying API. It is the tool schema placed between the API and the model.

Here are seven issues worth checking before releasing an MCP or AI-agent tool.

1. A description that is too vague

Descriptions such as "Searches documents" do not give an agent enough routing context. The description should identify the supported content, expected result, important limits, and a clear use case.

Better:

«Search indexed support documents and return the most relevant text excerpts. Use this when answering questions about product setup or troubleshooting. Do not use it for account-specific or real-time billing information.»

1. No boundary conditions

A useful description should also explain when the tool should not be used. Exclusions help an agent distinguish similar tools and avoid calls that cannot succeed.

Examples include:

• Do not use for personal account data.
• Do not use when the user requests current inventory.
• Do not use for destructive actions without confirmation.

1. Undocumented inputs

An input name such as "query", "id", or "limit" may seem obvious to its author, but the agent still has to guess the required meaning and format.

Each property should explain:

• What the value represents
• The expected format
• A realistic example
• Any important constraints

1. Missing required fields

If the schema does not identify the minimum necessary inputs as required, an agent may send an empty or incomplete call that cannot produce a useful result.

For example:

{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Natural-language search query, for example: password reset instructions"
}
},
"required": ["query"]
}

1. Unbounded numeric values

Inputs such as "limit", "page_size", or "timeout" should usually have sensible minimum and maximum values. Otherwise, extreme values can create slow, expensive, or unpredictable requests.

"limit": {
"type": "integer",
"description": "Maximum number of results to return",
"minimum": 1,
"maximum": 20,
"default": 5
}

1. Unknown arguments are accepted

Agents can occasionally invent plausible-looking parameter names. When an object schema accepts additional properties, those hallucinated arguments may pass validation unnoticed.

Where appropriate, add:

"additionalProperties": false

This turns an ambiguous call into an explicit validation error that can be diagnosed.

1. The schema is technically valid but difficult to route

JSON Schema validity is only part of the problem. An agent also needs to distinguish the tool from other available options. Tool names, descriptions, argument documentation, and exclusions should work together as routing instructions.

Before release, ask:

• Could an agent distinguish this tool from a similar one?
• Are the expected result and limitations clear?
• Can the minimum useful call be determined from the schema alone?
• Will unsafe or nonsensical values fail validation?

A practical review process

Reviewing tool schemas by hand is possible, but the same problems repeat across projects. I built ToolReady AI to automate an initial quality check and produce a prioritized report with recommended fixes.

The current founding beta is free and does not require a credit card. I am looking for developers willing to test it with real MCP or agent tools and report false positives, unclear recommendations, and missing checks.

Try it here: "https://toolready.dev" (https://toolready.dev)

I would especially like to know: Which schema mistake has caused the most trouble in your own agent projects?