gofri Why two g's? When I was a kid my grandma called me Gofri, and the family picked it up. She said the G hard, almost twice, so I write it twice.

Ohtools: inspect tool contracts before agents execute

My contribution
Design and implementation.
Scope
A shared tool registry, exploration contracts, validation, and CLI/MCP adapters.
Evidence
Implementation inspected at 9abeaa8; reconstructed examples are labelled.

Page by Julian Ramirez ·

A list of functions tells an agent what it can call. It may tell it very little about where to begin. Which tool belongs to this part of the workflow? What input does it expect? Does looking at it execute anything?

Ohtools organizes those questions around a shared tool registry. Definitions carry contracts, hierarchy gives them context, and adapters expose them through different interfaces. The result is a working map an agent can inspect before choosing an action.

The distinction that matters to me is between availability and understanding. Exposing a handler makes an action possible. Exposing its place in the workflow makes the choice easier to reason about.

My contribution and design scope

I built Ohtools around one registry that serves the CLI, MCP and documentation. The central design choice is to expose a tool’s structure before invoking its handler. This case follows that boundary through discovery, validation and execution, including where inspection can still run dynamic resolvers.

Keep one tool definition across interfaces

Without a shared definition, a CLI help page, an MCP descriptor and a documentation page can gradually describe different versions of the same tool. Ohtools derives those surfaces from the registry, keeping the tool’s description and declared schemas close to its implementation.

Tool definition
↳ CLI ↳ MCP ↳ Documentation
Mechanism, not a recorded runIllustrative schematic
Sources & implementation notes

This is useful beyond avoiding duplicated descriptions. It creates a concrete place to inspect the contract when one interface behaves unexpectedly. The shared definition can be the starting point for the investigation instead of another layer of documentation to reconcile.

Give tools relationships, not just names

A registry can represent groups and their tools, along with declared next-step information. That makes the surface navigable: an agent can move from a relevant part of the hierarchy toward a specific contract instead of treating every function as an unrelated option.

Registry
workspace
inspect validate run
Tool → input schema · output schema
Illustrative hierarchy · declared schemasIllustrative schematic
Sources & implementation notes

The example hierarchy is illustrative. The design decision is real: hierarchy and schemas are data the system can expose, rather than context that exists only in a human-written prompt.

Separate inspecting a contract from invoking its handler

Ohtools distinguishes exploration from execution. Exploration returns structural information and declared schemas without invoking the tool’s run handler. Execution crosses a different boundary: it processes input, calls the handler and processes output.

Use the controls to inspect that distinction. The browser example only changes the diagram; it does not execute any project tool.

Explore → metadata handler ── not called
Run → handler input → execution → output
Illustrative state comparison · no project commands executeIllustrative schematic
Sources & implementation notes

Inspection does not invoke the tool run handler. Dynamic next-step resolvers can still run during exploration; inspection is not a general purity or safety guarantee.

There is a useful nuance here. Dynamic next-step resolvers can run during exploration. “Does not call the tool handler” is therefore narrower than “cannot have any side effects.” That is the kind of detail an inspectable contract should help uncover, not hide.

Carry context into the next action

Inspection is valuable only if it informs the next choice. The sequence below follows a candidate action from reading its contract to validating input and running it. After execution, the runtime can return output together with next-step context.

inspect input shape + declared next steps
validate candidate input → schema
run handler → output → next
Illustrative workflow · validation requires declared schemasIllustrative schematic
Sources & implementation notes

When schemas are declared, validation surrounds the handler. Input is checked before execution; output is checked afterward. These checks help enforce a contract, but output validation cannot undo a side effect that has already happened.

Input schema → handler → Output schema
When schemas are declaredIllustrative schematic
Sources & implementation notes

The runtime parses input before the handler and output after it. A schema checks shape and constraints; it does not make side effects inherently safe.

That makes authorization, resource limits and consequential actions separate design concerns. Ohtools gives those concerns a clearer interface to work with; it does not make arbitrary execution inherently safe.

Use the map where it reduces uncertainty

The inspected project targets a Bun-based workflow with CLI and MCP stdio adapters. Start by exploring a small registry and checking whether its groups, schemas and next-step information answer the questions a new agent would otherwise have to guess.

The same emphasis on explicit contracts appears in Fake-End’s local API mocks and Plot’s specification boundaries. In each case, the representation becomes useful before the final action takes place.

Explore Ohtools documentation and examples →