Mahal Systems Overview › Agent type
Tool use
Choosing and calling tools, APIs and MCP servers correctly.
Specific to tool use
- 2.a.i
Reduce the tool surface: remove and consolidate tools, then defer the rest behind search
Offer the agent only the tools the task needs.
- 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.
- 2.a.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.
- 2.b.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.
- 2.b.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.
General optimizations with evidence from tool use
- 1.b.i
Match the model and its effort to each call site and query class
Pick the model per role or call site rather than one model everywhere, and set its reasoning effort and sampling parameters per site; tune each role's prompt to its model (GEPA raised every model tested at lower cost).
- 2.c.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.
- 3.a.i
Add worked examples to the prompt (few-shot), or curated example queries for data agents
Put a few solved examples of the task in the prompt (the input and the exact output wanted), or give a data agent commented example queries for its custom metrics and an index of past queries it retrieves per question.
- 3.a.ii
Avoid few-shot ruts
An agent's own history, and any examples in its prompt, act as few-shot demonstrations: when the context fills with near-identical action-observation pairs (twenty similar items in a row, a retried call), the model tends to copy their surface form instead of judging the current item.
- 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.
- 4.b.i
Filesystem-based agent state and checkpoints
Save the agent's state at each step boundary (the conversation, the workspace files, process state when it matters, and a ledger of external side effects) so a crashed or stuck run resumes or rolls back instead of starting over.
- 5.c.ii
Sub-agent architectures with clean contexts
Hand a context-heavy side task (code search, reading many files, documents or logs) to a sub-agent that starts with a fresh context and only the tools it needs, and have it return a short result or file references so the parent's context stays small.
- 6.a.i
Oracle-worker multi-model
Let a cheap model do the work and call an expensive one only when a trigger fires: a cascade escalates when the cheap answer looks unreliable or fails a check, a router picks the model before the call, and an advisor tool lets a cheap agent consult a stronger model mid-task.
- 6.b.i
Parallel tool execution for read-only calls
Let the model put several independent read-only tool calls (searches, fetches, file reads) in one turn and have the harness run them at once, while calls that write, share state or need another call's result run one at a time in the order the model emitted them.
- 6.b.ii
LLM map-reduce
Give each piece of a large or untrusted input its own tool-less model call that sees only that piece and must answer in a fixed schema, then combine the answers in code or in a reducer that never sees the raw text.
- 6.c.i
Code-then-execute (CaMeL)
Have a privileged model turn the trusted request into a small program before any untrusted data is read, then run it in an interpreter that labels every value with where it came from and checks a per-tool policy before each call, so injected text can neither add actions nor send private data to the wrong place.
- 6.c.ii
Plan-then-execute
Have the agent fix its tool calls (an ordered list or a dependency graph) from the trusted request before it reads any tool output, and let a controller execute only those calls, so injected text cannot add an action.
- 7.b.ii
Keep errors in context
Return every failed action to the model as an error it can read (the call, the cause, a capped trace) instead of swallowing the exception, retrying silently, returning an empty result or deleting the failed attempt, and collapse each error once it is resolved.
- 7.d.iii
ReAct loop
Run the agent as a loop: the model reasons, calls a tool, reads the result and picks the next step, until it answers or hits a cap.
- 10.a.i
Constrain what the agent can touch
Run the agent in an OS-level sandbox with a workspace path guard that resolves symlinks, scrub credentials from the command environment, run agent-written SQL read-only with timeouts and row caps, and set resource limits on generated code.
- 10.c.i
Contain sensitive data and untrusted input
Tokenize PII in the client so it never reaches the model, wrap untrusted tool and web results in taint delimiters, scan context files and skills for prompt injection, and state an explicit instruction-precedence order (user, repo, defaults, external data as data).