Serhii Shchoholiev on X: "Stop patching bad tools with essays on how to use them https://t.co/1kPngaAxwR" / X<br>Post

Log inSign up

Post

Serhii Shchoholiev

@sshchoholiev

Stop patching bad tools with essays on how to use them<br>How to build efficient Agent Tools<br>Many engineers think of Agent Tools as functions, but they aren't. They are closer to user actions.<br>With functions you try to keep them as atomic as possible, but for tools that might result in long tool call chains and make your agent slow, expensive and error prone. Tools operate in natural language space. That space is too large to say deterministically what will and won't work. We shared this work with OpenAI. Their read:<br>The best agent tools give Codex more data, help it find the right context, take the right action, and go deeper when needed. Hypha’s work shows how thoughtful MCP design can make Codex more useful in real-world workflows.<br>- Codex Team @ OpenAI<br>Over a year of building the Hypha platform, our tools evolved multiple times to satisfy expanding requirements. When we migrated from a custom agent loop to an off the shelf harness, issues started to come up: our agent called wrong tools, the tool calls themselves were malformed, overall, our agent was taking more and more turns to navigate the database - increasing the latency. We patched the tools quickly by piling on instructions, which in turn drove up cost. Database access is the primitive our agents rely on, so we had to fix it. We then used autoresearch to improve our tools against the SQL eval, which delivered results, but no reusable insights.<br>That’s why we ran a leave-one-out ablation study of Hypha’s Agent Tools on a SQL retrieval eval: three financial data models, 300+ runs, three trials per case to cut noise. What follows is primarily a mindset of how you should think of Agent Tools rather than a todo list of exact changes. Each section is a lever we tested: observation first, then the change.<br>Limiting tool output size<br>Most harnesses cap tool output to manage context, but handle limits differently:<br>Codex keeps the head and tail of a huge tool call result (~11k tokens from each end) and drops the middle.<br>Claude Code offloads all MCP results over 25k tokens to the filesystem and instructs the agent to use Grep or Bash to read them.<br>Neither approach is likely optimal for your tools. A better way is to shrink the output gracefully. Give each tool filters that control how much a single call returns, and check the size before answering: estimate tokens → over the limit? → tighten the filter → return the trimmed result with a note explaining what was cut and why, for us it looks like:<br>get_schema(includeColumns) → over 25k tokens → get_schema() + hint: full schema is too large, use get_columns() to narrow down search<br>Why not just return an error - “output too large” - and keep the context clean? An error burns a turn and gives the agent nothing. A trimmed result often has enough to finish the task - and when it doesn’t, the filters let the agent fetch exactly what’s missing instead of starting over. You can see the impact on the chart below. Both latency and cost go down with output limits. Codex makes more tool calls, but fewer turns - and turns cost more than a few more output tokens.<br>Both the Claude Agent SDK and the Codex SDK expose a setting to control the output limit:<br>Codex SDK - tool_output_token_limit in config.toml / models.json, default 10k tokens.<br>Claude Agent SDK - the MAX_MCP_OUTPUT_TOKENS env var, default 25k tokens.<br>To compare the two harnesses fairly, we set Codex output limit to 15k, since the tokenizers differ - Opus 4.8 splits the same text into ~1.5x more tokens than GPT-5.5, so equal raw caps aren't equal budgets.<br>Analyzing agent traces, we observed Claude behaving as expected: limit hit -> filesystem -> Grep, resulting in more tool calls and turns. Codex, on the other hand, has no way to inspect the output after hitting a limit - but GPT-5.5, instead discovers the SQL schema by reading one row of each table to get all the columns, using the tool that executes arbitrary read-only SQL.<br>Add progressive disclosure<br>Agents rarely need the whole dataset to answer a question, loading it all just burns context and money. A more appropriate alternative is progressive disclosure: reveal data on demand.<br>Applying it well is the real work. An obvious approach is to drill down level by level. In our case we have 3: tables → groups → columns. In our terms that is: Loans → Terms → Amount. But this has a failure mode:<br>Both the Terms and Funding groups under Loans have an Amount column — the agreed amount versus the actual one. The agent finds Terms' Amount first, decides it's done, and answers — never checking Funding held the one the question needed. Watch the video below for visualization.<br>A human would make the same mistake. Drill-down only walks one direction - depth. But your data likely isn't just a tree. Disclosure can run along several independent directions - not just...