> ## 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.

# Tool

> Complete field reference for tool definition files.

Each `app/tools/*/config.terse` defines one MCP tool — its execution strategy, inputs, mappers, authentication, and caching behavior.

## Full schema

```yaml app/tools/get-user-profile/config.terse theme={null}
name: get-user-profile
description: 'Retrieve a user profile by primary key'
use: primary-db
statement: |
  SELECT id, name, email, created_at
  FROM users
  WHERE id = {{ inputs.user_id }}
inputs:
  user_id:
    type: int
    description: 'User primary key'
mappers:
  input: './validate-input.ts'
  output: './format-output.ts'
auth:
  plugin: api_key
  policy:
    value: '{{ env.API_KEY }}'
cache:
  enabled: true
  ttl: 120
```

## Field reference

<ParamField body="name" type="string">
  MCP tool name. Must be unique across all tools.

  Default: directory name (e.g., `get-user` from `app/tools/get-user/`).
</ParamField>

<ParamField body="description" type="string">
  Human-readable tool description. Exposed in the `tools/list` MCP response.
  Strongly recommended for agent discoverability.
</ParamField>

<ParamField body="use" type="string">
  Adapter name for statement execution. References an adapter identifier defined in `app/adapters/`.

  {' '}

  <Tip>
    `use` must be a single adapter name. Array values are rejected during
    validation.
  </Tip>

  <Warning>
    Exactly one of `use` or `handler` must be set. A tool cannot define both.
  </Warning>
</ParamField>

<ParamField body="statement" type="string">
  SQL query or database command. Supports `{{ env.VAR }}` and `{{ inputs.field }}` placeholders. Use YAML multiline syntax (`|`) for readability.

  ```yaml theme={null}
  statement: |
    SELECT id, name, email
    FROM users
    WHERE id = {{ inputs.user_id }}
  ```
</ParamField>

<ParamField body="inputs" type="object">
  Map of input parameter definitions. Each key becomes a named parameter in the MCP tool's input schema.

  <Expandable title="input field properties">
    <ParamField body="type" type="string" required>
      Input data type. Allowed values: `string`, `int`, `float`, `boolean`, `datetime`.
    </ParamField>

    <ParamField body="description" type="string">
      Human-readable description. Exposed in the MCP input schema for agent consumption.
    </ParamField>

    <ParamField body="optional" type="boolean" default="false">
      Whether the input can be omitted by the caller.
    </ParamField>

    <ParamField body="default" type="string">
      Default value when the caller omits this input. Always a string; converted to the declared type at runtime.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="handler" type="string">
  Optional handler script path for fully script-backed tools. When set, it replaces
  database execution entirely. The handler receives inputs and returns results directly.

  Use `path#exportName` to call a non-default export.
  Without `#exportName`, Hyperterse calls the script's `export default` (function name ignored).
</ParamField>

<ParamField body="mappers" type="object">
  Optional mapper script paths for pre/post processing. All paths are relative to
  the tool directory.

  <Expandable title="properties">
    <ParamField body="input" type="string">
      Input mapper script path. Runs before statement execution. Receives raw inputs
      and returns modified inputs.

      Use `path#exportName` to call a non-default export.
      Without `#exportName`, Hyperterse calls the script's `export default` (function name ignored).
    </ParamField>

    <ParamField body="output" type="string">
      Output mapper script path. Runs after statement execution. Receives raw results
      and returns modified results.

      Use `path#exportName` to call a non-default export.
      Without `#exportName`, Hyperterse calls the script's `export default` (function name ignored).
    </ParamField>
  </Expandable>

  <Tip>
    If mapper/handler scripts are omitted, convention-based discovery applies — see [Scripts](/concepts/scripts).
  </Tip>
</ParamField>

<ParamField body="auth" type="object">
  Tool-level authentication. Omitting this block entirely makes the tool unauthenticated.

  <Expandable title="properties">
    <ParamField body="plugin" type="string" required>
      Registered auth plugin name. Built-in plugins: `allow_all`, `api_key`.
    </ParamField>

    <ParamField body="policy" type="object">
      Plugin-specific parameters. For `api_key`, set `value` to the expected key or an `{{ env.VAR }}` reference.

      ```yaml theme={null}
      auth:
        plugin: api_key
        policy:
          value: "{{ env.API_KEY }}"
      ```
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="cache" type="object">
  Per-tool cache settings. Overrides the global cache configuration from `.hyperterse`.

  <Expandable title="properties">
    <ParamField body="enabled" type="boolean">
      Whether caching is active for this tool. Inherits from `tools.cache.enabled` if not set.
    </ParamField>

    <ParamField body="ttl" type="integer">
      Cache TTL in seconds for this tool. Inherits from `tools.cache.ttl` if not set.
    </ParamField>
  </Expandable>
</ParamField>

## Validity rules

A tool is valid when exactly one of these conditions is met:

1. `use` is defined (database-backed tool).
2. `handler` is defined (script-backed tool).

<Warning>
  Tools with neither `use` nor `handler` — or with both — are rejected during
  validation.
</Warning>

## Runtime mapping

* Tool configs become live tool definitions when the server starts or reloads.
* Project tools are discoverable via MCP `tools/call` on `search` (ranked metadata results).
* Project tools execute via MCP `tools/call` on `execute` with:
  * `tool` = resolved tool name
  * `inputs` = caller payload validated against `inputs` definitions
* `auth` runs before execution and can reject requests.
* `mappers.input` runs before statement/handler execution; `mappers.output` runs after.
* `handler` tools run script-backed execution; `use` + `statement` tools run connector-backed execution.
* `cache` settings map to runtime in-memory result caching policy.
* Tool calls emit MCP progress and logging notifications during execution.

<Tip>
  `tools/list` intentionally returns the transport entry tools (`search`,
  `execute`) as a core runtime design. Your configured project tools are
  discovered through `search` and invoked through `execute`.
</Tip>

## JSON Schema

Editor validation: `schema/tool.terse.schema.json`. Associate with `**/tools/**/config.terse`. See [Configuration schemas](/reference/configuration-schemas).