The Art of Tool Descriptions
Same functionality, but good vs bad descriptions differ by 3× in success rate — a contrast experiment
THE QUESTION THIS PAGE ANSWERS
ANSWER FIRSTWhat is the key idea behind “The Art of Tool Descriptions”?
Same functionality, but good vs bad descriptions differ by 3× in success rate — a contrast experiment
Make the claim earn its place. Use this page as a decision aid, not a definition to memorize. Connect the idea to one real task, one observable result, and one failure that would change your mind.
Write one question you could answer with evidence after trying this idea.
A conclusion that sounds complete but leaves the key assumption untested.
How “Conclusions & Critical Thinking” becomes executable
“Same functionality, but good vs bad descriptions differ by 3× in success rate — a contrast experiment” is not about a magic phrase. It is about giving the model enough information to know who the work is for, what must be done, and what counts as acceptable.
Background sets direction; constraints set the boundary
“Same functionality, but good vs bad descriptions differ by 3× in success rate — a contrast experiment” shows why a useful request separates the task, audience, source material, output format, and constraints. Without background, the model guesses. Without acceptance criteria, fluent text is not evidence that the task is complete.
More words do not guarantee a better result
Turn “Same functionality, but good vs bad descriptions differ by 3× in success rate — a contrast experiment” into a small experiment: change only one of background, requirements, or constraints while keeping the rest fixed, then observe which layer actually changes the output.
Take the example one step further
The page first makes this point: “Core conclusion: A tool description = the user manual for the model. The clearer the manual, the more accurately the model uses the tool. This is not just an engineering problem. Product managers should write t…”. Turn it into a small exercise rather than a sentence to memorize: write down the input, expected result, and the observation that would make you re-check the judgment.
Carry the judgment into the next situation
Build a request layer by layer: task and audience first, material and output rules next, constraints and acceptance checks last. Change one layer at a time so you know what actually helped.
- “Conclusions & Critical Thinking”: Core conclusion: A tool description = the user manual for the model. The clearer the manual, the more accurately the model uses the tool. This is not just an engineering problem. Product managers should write t…
Finish with a small, reversible exercise: put the page's judgment into a real input, write the expected result, and name the signal that would make you stop and verify it.
I turned one judgment from this article into a small experiment I could run today. Knowing what to observe next is more useful than simply remembering the conclusion.
After reading this, I first looked for the conditions behind the idea instead of copying the method into a project. That order made the later trade-offs much clearer.
When this judgment reaches real work, which constraint should be added first? I am curious which step matters most between reading and the first practical attempt.
No discussion on this article yet.