PullMD Part 6: Setup for Agents
One afternoon I only meant to tidy up the interface. What came out of it was a help page and a fairly stupid error in my own thinking about my own service.
The Thought That Kicked It All Off
We were talking about share links and how long they actually live. And then something struck me:
“Ah, interesting, so an AI agent could fetch a subreddit link again and again and would always have the newest posts, or the ones on the page at least… cool. We should write that kind of information onto a built-in help page, because you forget things like this and after a few weeks or months you don’t know any more. A lot of projects don’t have that.”
The second part is the more important one in hindsight. I really do forget the quirks of my own tools. After three months I no longer know whether the cache holds for an hour or a day, and then I just try it out instead of looking it up. It would obviously be good to be able to look that up inside the service itself.
The Help Page
So /help, bilingual, in the same design as the rest.
It says what you forget:
- How long a result stays fresh and when it gets fetched again
- How long a share link lives
- That an agent can fetch a subreddit link again and again and gets the newest posts that way
- Which parameters the endpoint knows
- What sits in the header of the markdown
- How the service tells whether a browser, the app or an agent is asking
Plus a section I hadn’t had anywhere before: setup for AI agents. Two boxes to copy, one of them a ready-made text you can put in front of any chatbot, and the skill from Part 4 as a ZIP to download.
The ZIP is created automatically from the skill directory when the container is built. Nine files, nine kilobytes. Unpack it and the setup is already in there, nothing to gather by hand.
For MCP the page said “coming soon” for the time being. We’ll get to that in Part 7.
One Claim Wasn’t True
While writing down the subreddit tip, I thought the idea through once more: that an agent fetches the same link over and over and gets the current state every time. And realised that it doesn’t work that way at all:
“The share link only really makes sense if I can use it to pull the content fresh again and again. Otherwise I don’t need the share link, I already have the old text.”
Up to that point the share link was a snapshot. You call it up and get exactly what was there on the first fetch. For “send someone an article” that’s right. For an agent that wants to know what’s going on in a subreddit right now, it’s useless.
So the error in reasoning wasn’t in the code, it was in what I had claimed myself half an hour earlier.
The Snapshot Becomes an Endpoint
The rebuild was small. When a share link is called, the service now looks at the age. If the state is older than an hour, it fetches the source again and writes it back. The identifier stays the same.
Two details mattered here:
-
It has to derive from the old markdown whether comments were included back then and which language the answer was in. Otherwise the refresh returns something different from the first time.
-
And if the refetch fails because the source is gone or the network is stuck, it keeps serving the old state. A share link that suddenly says 404 would be worse than one showing something slightly old.
That way an agent only needs to know a short identifier. No URL to manage, no parameters to remember. Fetch it once, and what comes back is current.
That this very endpoint would become one of three tools for Claude two hours later wasn’t planned at that point.
Part 6 of 15 in the PullMD series.
← PullMD Part 5: Measuring the Wrong Engine | PullMD Part 7: The MCP Server →