> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperterse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools

> How tool definitions specify MCP tools, input schemas, and execution strategies.

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`:

```yaml theme={null}
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:

```yaml theme={null}
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 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.

```yaml theme={null}
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](/runtime/caching) for the full cache model.

## Further reading

See [Tool configuration reference](/reference/tool-config) for the complete field specification, including input properties, mapper options, and cache overrides.