Each app/tools/*/config.terse defines one MCP tool — its execution strategy, inputs, mappers, authentication, and caching behavior.
Full schema app/tools/get-user-profile/config.terse
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 MCP tool name. Must be unique across all tools. Default: directory name (e.g., get-user from app/tools/get-user/).
Human-readable tool description. Exposed in the tools/list MCP response.
Strongly recommended for agent discoverability.
Adapter name for statement execution. References an adapter identifier defined in app/adapters/. use must be a single adapter name. Array values are rejected during
validation.
Exactly one of use or handler must be set. A tool cannot define both.
SQL query or database command. Supports {{ env.VAR }} and {{ inputs.field }} placeholders. Use YAML multiline syntax (|) for readability. statement : | SELECT id, name, email FROM users WHERE id = {{ inputs.user_id }}
Map of input parameter definitions. Each key becomes a named parameter in the MCP tool’s input schema. Show input field properties
Input data type. Allowed values: string, int, float, boolean, datetime.
Human-readable description. Exposed in the MCP input schema for agent consumption.
Whether the input can be omitted by the caller.
Default value when the caller omits this input. Always a string; converted to the declared type at runtime.
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).
Optional mapper script paths for pre/post processing. All paths are relative to
the tool directory. 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).
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).
If mapper/handler scripts are omitted, convention-based discovery applies — see Scripts . Tool-level authentication. Omitting this block entirely makes the tool unauthenticated. Registered auth plugin name. Built-in plugins: allow_all, api_key.
Plugin-specific parameters. For api_key, set value to the expected key or an {{ env.VAR }} reference. auth : plugin : api_key policy : value : "{{ env.API_KEY }}"
Per-tool cache settings. Overrides the global cache configuration from .hyperterse. Whether caching is active for this tool. Inherits from tools.cache.enabled if not set.
Cache TTL in seconds for this tool. Inherits from tools.cache.ttl if not set.
Validity rules A tool is valid when exactly one of these conditions is met:
use is defined (database-backed tool).handler is defined (script-backed tool).
Tools with neither use nor handler — or with both — are rejected during
validation.
JSON Schema Editor validation: schema/tool.terse.schema.json. Associate with **/tools/**/config.terse. See Configuration schemas . 
