Mahal Systems Overview › 2Tools
Tools
6 optimizations in 3 sub-categories.
a.Refactoring
Refactor & combine
- i.
Reduce the tool surface: remove and consolidate tools, then defer the rest behind search
Offer the agent only the tools the task needs.
- ii.
Rewrite the tool surface: names, schemas, descriptions
Change what the model sees of each tool without touching its implementation: a distinct name, a strict schema (enums, required fields), and a description with fixed sections (what it is for and when to use it versus sibling tools, defaults and limits, error modes, side effects), plus a usage example for complex parameters.
- iii.
Choose how the agent acts: typed tools, code execution, or shell, matched to the model and task
Decide the action interface deliberately, by model and by task, and provision what it needs.
b.Avoiding misuse
- i.
Make tool calls and tool results fail soft, and retry transient failures
Keep a failed call from ending the run: validate tool calls and model responses, return tool errors to the agent as results, and retry only failures that are transient and safe to repeat.
- ii.
Tell the agent when to use each tool, in context it always sees
For each tool or skill that is under-used or misused, add an explicit trigger rule where the model always sees it (system prompt, AGENTS.md): the situation that calls for the tool, and what to use it instead of (e.g.
See also
- 2.a.ii
Rewrite the tool surface: names, schemas, descriptions
Change what the model sees of each tool without touching its implementation: a distinct name, a strict schema (enums, required fields), and a description with fixed sections (what it is for and when to use it versus sibling tools, defaults and limits, error modes, side effects), plus a usage example for complex parameters.
- 3.b.ii
Mask tools instead of removing them
When the tools an agent may use change mid-task (by mode, phase or permission), declare every tool once, keep the definitions byte-stable, and restrict the choice another way: OpenAI's allowed_tools or tool_choice "none", Anthropic's appended tool_removal and tool_addition blocks, a decode-time logit mask or grammar on self-hosted models, and a harness check that rejects calls outside the allowed set.
c.Trimming results
Return only what the model needs
- i.
Bound tool output: cap it, or write it to a file the agent can read
Cap the characters of tool output kept per call (VeRO settled near 15-20 KB on TerminalBench), or, better, write long output to a file and return its path with a short head, so the agent can read more if it needs to.