DEV Community

Mads Hansen
Mads Hansen

Posted on

What makes a good MCP tool definition (and what makes a terrible one)

#mcp #ai #programming #architecture

MCP tools are simple in theory: you define a function, describe what it does, and AI models call it when relevant.

In practice, the quality of your tool definition determines whether your AI is actually useful or constantly confused.

Here are the patterns that separate good from bad.

The naming problem

Bad:

{
  "name": "get_data",
  "description": "Gets data from the system"
}
Enter fullscreen mode Exit fullscreen mode

This is useless. Every tool "gets data." The AI has no idea when to call this vs anything else.

Good:

{
  "name": "get_overdue_device_patches",
  "description": "Returns a list of devices that have not received a security patch in the specified number of days. Defaults to 30 days if not specified."
}
Enter fullscreen mode Exit fullscreen mode

Now the AI knows exactly when to call this — when someone asks about patch status, overdue updates, or device compliance.

Rule: Name your tool like a function a senior engineer would write. Verb + noun + context.

The parameter problem

Bad:

{
  "parameters": {
    "query": {
      "type": "string",
      "description": "The query"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

What query? SQL? Natural language? A search string? The AI has to guess.

Good:

{
  "parameters": {
    "days_since_last_patch": {
      "type": "integer",
      "description": "Number of days since last patch. Returns devices that haven't been patched within this window. Default: 30",
      "default": 30
    },
    "os_filter": {
      "type": "string",
      "description": "Optional: filter by OS type ('windows', 'macos', 'linux'). Omit to include all.",
      "required": false
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Explicit parameters with real descriptions. The AI knows exactly what to pass.

The scope problem

The most common mistake: tools that try to do too much.

Bad: One tool that takes a "query type" parameter and branches internally.

Good: Separate tools for separate concerns. get_active_devices, get_overdue_patches, get_device_by_id.

Small, focused tools are easier for AI models to reason about. They also fail more gracefully.

Real-world example

At Conexor.io, we generate MCP tool definitions automatically from database schemas. The quality of those definitions directly affects query accuracy.

When we added column-level descriptions and specific parameter types, the accuracy of AI-generated queries improved significantly — fewer hallucinated column names, fewer type mismatches.

The lesson: MCP tool quality is a first-class concern, not an afterthought.

Good tools make AI feel like it knows your system. Bad tools make it feel like it's guessing.

The difference is almost entirely in the definition.

Top comments (0)