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

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" } 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." } 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" }