> inline examples in the description beat external documentation every time. The agent won't browse to your docs page.

That seems... surprising, and if necessary something that could easily be corrected on the harness side.

> The schema side matters too - clean parameter names, sensible defaults, clear required vs optional. It's basically UX design for machines rather than humans.

I don't follow. Wouldn't you do all those things to design for humans anyway?

*Clean parameter names, sensible defaults, clear required vs optional. It's basically UX design for machines rather than humans.*

But it's the same points you should follow when designing a human readable docs(as zahlman said above). Isn't it?