Skip to main content
A tool definition is the central abstraction in Hyperterse. Each tool config file defines exactly one MCP tool: name, description, how it runs, inputs, authentication, and caching. On startup, every valid definition appears in the MCP tools/list response.

Execution models

A tool definition’s execution model is determined by its configuration. There are two primary models. DB-backed tools execute a SQL or database command through a connector. They require use (the adapter name) and statement:
Script-backed tools delegate execution to a TypeScript handler. No adapter or statement is needed:
Hybrid tools combine a DB adapter with mappers for pre-processing and post-processing. Execution order is: auth, input mapper, DB execution, output mapper.

Tool naming

The MCP tool name comes from the tool definition. If the config sets a name field, that value wins. Otherwise the folder name becomes the tool name (for example a folder named get-user yields the tool get-user). Names must be unique—Hyperterse rejects duplicates when you build or start.

Input schema

The inputs block defines typed parameters that the tool accepts.
Supported types are string, int, float, boolean, and datetime. Required inputs without a default must be provided by the caller. References in statements use {{ inputs.field_name }} placeholders.

Caching

Tools can override the global cache policy with a cache block. See Caching for the full cache model.

Further reading

See Tool configuration reference for the complete field specification, including input properties, mapper options, and cache overrides.