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

MCP tools: define a function and a description; AI models call them when relevant.

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

Name tools like a senior engineer would: verb + noun + context — avoid generic names (e.g., don’t use get_data; use get_overdue_device_patches with a clear description).

Specify explicit parameters, types, defaults, and clear descriptions rather than vague fields (e.g., days_since_last_patch with default 30; os_filter optional).

Keep tools focused and separate concerns; Conexor.io found that adding column-level descriptions and parameter types improved AI query accuracy.