Developer shares key lessons on designing MCP server tools for AI accuracy

A developer building PasteSheet, a read-only Google Sheets MCP server, found that correctly functioning code still caused Claude to make wrong decisions roughly one-third of the time. The root cause was not faulty implementation but poorly written tool names, descriptions, argument docs, and error strings — the only parts an AI model actually reads. A key fix was adding a dedicated discovery tool that instructs the model to fetch real column names before querying, which significantly reduced errors like invented column names returning false empty results. The author also found that offering multiple search modes — exact, partial, and full-text — led the model to consistently pick the loosest option, since it appeared least likely to fail. These lessons, originally learned while writing a PHP server, are presented in Python using the official MCP SDK to reach a broader developer audience.