Extend with Tools
Extend with Tools
Custom tools let agents call your code as naturally as they call built-in file or shell tools. Define the input schema, write the handler, and register it with the agent.
Why extend with tools
Built-in tools cover files, shells, and common reasoning patterns. Real applications often need domain-specific actions, such as querying an internal API, reading a feature flag, or updating a project management ticket. Custom tools expose those actions to the agent with the same interface as built-in tools.
Tool definition schema
A tool has three parts:
- Name - a unique identifier using snake_case.
- Description - a clear explanation that helps the model decide when to call the tool.
- Parameters - a JSON Schema object describing the arguments.
- Handler - the function that runs when the tool is invoked.
Tip: Write descriptions as if you are instructing the model. Include examples and edge cases.
Define a tool in TypeScript
The defineTool helper validates the parameter schema and serializes the result for the model.
Register the tool with an agent
Define a tool in Python
Connect external tools with MCP
If a tool already exists as a service, you can expose it through the Model Context Protocol instead of writing a handler. MCP lets Autohand discover and call tools hosted in a separate process.
See Connect to external tools with MCP for setup instructions.
Best practices
- Keep handlers focused on a single operation. The model composes multiple tool calls to solve larger tasks.
- Return structured data when possible. JSON results are easier for the model to reason about than free text.
- Validate and sanitize arguments inside the handler, even when JSON Schema is enforced.
- Throw or return errors with context so the model can retry or ask for clarification.
- Load secrets from environment variables, never from arguments or source code.