I'm working on an SEO tool and I want my agent to use a specific API for backlink analysis. I’ve seen the docs on Browserless and Serper, but how do I create a truly custom tool that passes complex JSON objects between agents? Every time I try, the agent gets confused by the schema.
3 answers
The trick with custom tools is to use the Pydantic library to define your input schema clearly. When the agent knows exactly what fields to expect, the hallucinations drop to near zero. I built a custom tool for Moz API integration last year, and I found that providing 2-3 examples of the JSON output in the tool's description field helped the agent parse the results much better. Also, ensure your tool returns a string or a very clean dictionary, as overly nested objects can still trip up some smaller LLMs.
Are you decorating your functions with the @tool decorator correctly? Sometimes the docstring of the function is what the agent uses to understand the tool, so it needs to be very descriptive.
I usually suggest testing the tool in isolation first. If a basic Python script can't parse the JSON, your agent definitely won't be able to handle it either.
Good point, Rebecca. Isolation testing is key. I realized my API was returning a 403 error which was the real reason the agent was "confused" by the data!
I am using the decorator, but my docstrings were a bit vague. I'll try being more explicit about the required parameters and see if the agent picks it up better.