Skip to main content
A tool definition is the central abstraction in Hyperterse. Each app/tools/*/config.terse file defines exactly one MCP tool — its name, description, execution strategy, input schema, authentication policy, and caching behavior. When the server starts, every valid tool definition is registered as a callable tool 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: 
description: 'Retrieve a user by their identifier'
use: primary-db
statement: |
  SELECT id, name, email, created_at
  FROM users
  WHERE id = {{ inputs.user_id }}
inputs:
  user_id:
    type: int
    description: 'Primary key of the user record'
auth:
  plugin: allow_all
Script-backed tools delegate execution to a TypeScript handler. No adapter or statement is needed: 
description: 'Retrieve current weather conditions for a location'
handler: './weather-handler.ts'
auth:
  plugin: allow_all
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 is used. Otherwise, the directory name becomes the tool name. app/tools/get-user/ becomes get-user. Tool names must be unique — duplicates are rejected at compile time.

​
Input schema

The inputs block defines typed parameters that the tool accepts. 
inputs:
  user_id:
    type: int
    description: 'Primary key of the user'
  include_inactive:
    type: boolean
    description: 'Whether to include deactivated accounts'
    optional: true
    default: 'false'
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.