Coté

Coté

Writing good docs is important for agentic AI and Model Context Protocol, and developers are terrible at writing good docs

One quick things up-top: this week (tomorrow!), get an overview and demos of the private AI stack and development frameworks we’ve been working on at Tanzu. Register to check it out online, either live or the recording after the event.

Spy on the DM with Model Context Protocol Servers in Java

Here’s my latest walk-through is writing Model Context Protocol Server tools…to play D&D. Here, I build some slightly more complicated Oracles and show how to do logging. I attempt to get into the mind of the AI by asking it tell me why it’s calling an MCP tool. Claude surprisingly tight-lipped!

While making this I realized that writing good docs is more important than ever when you’re doing this kind of agentic AI programming. Instead of just writing a specification that the AI uses to call your tool (the “MCP Client”), you need to explain the tool to it: how to use it, why you’d use it, even your intentions for it. What’s the point of this tool, what are examples of using it?

That is so much different than how most developers thing of documentation. In fact, most developers don’t think about documentation at all. Most don’t write it, and when you read the docs, a lot is just not good.

So, when you’re writing these little AI tools, start thinking differently about how you document the tools. It’s obvious to say, but easy to forget: you need to explain them as you would to a human, not a computer.

Check out the first video which goes over the basics of Model Context Protocol and builds a simple oracle. You can get the code for all of this in my EasyChatDM repo.

Recent Garage Chairs of Amsterdam, impressive haul in Duivendrecht.

Relative to your interests

Recent Garbage Chairs of Amsterdam, San Jose, California edition.

Wastebook

  • “GAFAM refers to Google, Amazon, Facebook, Apple, Microsoft.” The new FANG. ”During his tenure, he delivered ‘normcore,’ ‘cringecore,’ and ultimately, the end of the ‘-core’ suffix altogether as fashion moves in the direction of something more “boom boom.”” All the great cores.

  • “He’s got his own Bobcat for no reason!” “He’s living the dream!” RotL #574.

  • “How long does it take to eat a tunafish sandwich in a bathroom stall?” Mythic Quest, s1e6. “Threads has no character. It feels like the conference room at any three-star chain hotel.” Post-twitter.

  • ”Yesterday I saw a bag of chips at the store that was $14.99. Beef tallow potato chips. This wasn’t Erewhon. The bag of chips was small. Things are stupid.” vibe-check.

  • ‘Columnists learn over time that it is unwise to write about one’s weirder foibles because instead of making you more accessible through charming self-deprecation, it can instead make you less accessible because you might seem a hapless feeb or a worrisome creep – such as if you wrote "Hey, you know how sometimes, when you haven’t changed your underpants in a week and a half …. "?’ - Remember to Wipe Carefully

  • “As a film maker, you try to solve your money problems with creative new techniques that that look good, but that are also cheap. There’s the battle, but that’s the joy of what we were doing…” Ralph Bakshi on Wizards.

Recent Garbage Chairs of Amsterdam, Shoreditch, London edition.

Conferences

Events I’ll either be speaking at or just attending.

Racing Toward AI App Delivery with Tanzu, April 16th, online, speaking. CF Day US, Palo Alto, CA, May 14th, speaking. NDC Oslo, May 21st to 23rd, speaking. SREDay Cologne, June 12th, speaking.

Logoff

Next month, at Cloud Foundry Day you can come to an in-person workshop for even more. I’ll be there, going over lessons learned from programming agentic goblins, as well as MC’ing. I also have a talk at Cloud Foundry Day proposing a new marketing plan for Cloud Foundry.

@cote@hachyderm.io, @cote@cote.io, @cote, https://proven.lol/a60da7, @cote@social.lol