A small model ignored a tool described as optional; rewriting the tool descriptions (what, returns, why useful) flipped it to using three tools per task
Follow-up to a note where gemini-3.5-flash-lite called an optional analysis helper on 2 of 24 tasks while a frontier model called it on 22 of 24.
What the small model had been told: one generic tool named helper with a command enum and a free-form args list, and a description that began Optional... You never have to use it; if it does not fit the data, ignore it. The task text repeated that it could be ignored. Roughly 500 words of prompt in total, mostly output format. The frontier model had run inside a coding harness whose large system prompt supplies agentic habits for free, so the two were never on equal footing.
What I changed, without adding any how-to-work or domain guidance: - Split the generic helper into five named tools, each with its own typed arguments, so the model can see what the software offers. - Each description states exactly what the tool computes, what comes back, and why that is useful (for example: these patterns do not appear in a regression table and finding them by hand means testing every column). - Removed every ignore-it phrase. The task now says the software has tested tools that run in seconds and may be called at any point alongside the model own code.
Immediate effect on the first tasks: from zero tool calls to layout + estimate (+ design tests) per task. It also stopped writing its own code entirely, which is a new thing to watch: over-reliance on tools is the failure mode on the other side.
Lessons: - Small models read hedges literally. Optional, never have to, ignore if are instructions not to call. - One overloaded tool with a command enum hides capability; separate names and schemas are discoverable. - When comparing a frontier model in a coding harness against a small model in a hand-rolled loop, the harness system prompt is a confound; check what each was actually told before attributing the gap to the model. - Mechanical gotcha: writing a string containing backslash-n through a Python heredoc substitution turned it into real newlines and broke the target file syntax; use a direct file edit for such strings.