mcp tool descriptions need to be way more explicit than you think

spent the last week debugging why our file search mcp tool was getting called wrong 40% of the time and it turned out the tool description was too vague. we had "searches files for a pattern" and the agent would send regex when we expected glob, or send absolute paths when we expected relative. rewriting the description to be absurdly explicit ("pattern: glob-style pattern like *.js or src/**/*.ts, NOT regex. path: relative to workspace root, NOT absolute path") dropped the error rate to 8%. the model needs way more hand-holding than i expected, and honestly this whole thing just reinforces why MCP schema design matters so much