> ## 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.
# Execution pipeline
> Deterministic execution flow for tool invocations from tool resolution through response serialization.
Every `tools/call` request passes through a deterministic pipeline. The stages are identical for DB-backed and script-backed tools — only the execution step differs. If any stage fails, execution halts immediately and an error response is returned.
## Tool resolution
Hyperterse matches the tool name from `tools/call` to the tool definition it loaded for that server run.
If no tool matches, a JSON-RPC error is returned with code `-32601`.
## Authentication
If the tool defines an `auth` block, the configured plugin is invoked with the request context and policy parameters.
* Plugin returns `nil`: authentication passes; the request continues.
* Plugin returns an error: the request stops; the error goes back to the caller.
* No `auth` block: stage is skipped entirely.
## Input transform
If `mappers.input` is configured or discovered by convention, the mapper script's `export default` function executes in the embedded runtime.
Payload:
```json theme={null}
{
"inputs": { "user_id": 42 },
"tool": "get-user"
}
```
The returned object replaces the inputs for all subsequent stages. Throwing an error stops processing.
If no input transform is configured, inputs pass through unchanged.
## Execution
The execution stage branches based on the tool's configuration. Only one path runs per invocation.
### Script-backed tools
When `handler` is configured, the handler script's `export default` function executes in the embedded runtime. The return value becomes the execution result.
### DB-backed tools
When `use` and `statement` are configured, the executor runs six substeps:
1. Input validation — validate all declared inputs against type definitions. Missing required inputs and type mismatches produce errors.
2. Environment substitution — resolve `{{ env.VAR }}` placeholders. Missing variables produce errors.
3. Input substitution — replace `{{ inputs.field }}` placeholders with post-transform values. Substitution is textual.
4. Cache check — if caching is enabled, compute the cache key from tool name + statement hash. On hit, return cached result and skip connector execution.
5. Connector execution — run the statement against the configured connector and return row/object results.
6. Cache store — on miss, store the result with the configured TTL.
## Output transform
If `mappers.output` is configured or discovered by convention, the mapper script's `export default` function executes in the embedded runtime.
Payload:
```json theme={null}
{
"results": [{ "id": 42, "name": "Jane Doe", "email": "jane@example.com" }],
"tool": "get-user"
}
```
The returned value replaces the result for response serialization. Throwing an error stops processing.
If no output transform is configured, the raw result is used directly.
## Response serialization
The final result is JSON-encoded and wrapped in an MCP content block:
```json theme={null}
{
"content": [
{
"type": "text",
"text": "[{\"id\":42,\"name\":\"Jane Doe\",\"email\":\"jane@example.com\"}]"
}
]
}
```
## Error propagation
| Stage | Error condition | JSON-RPC code |
| ------------------- | ------------------------------ | ------------- |
| Tool resolution | Tool name not found | `-32601` |
| Authentication | Plugin returns error | `-32000` |
| Input transform | Script throws | `-32000` |
| Input validation | Missing input or type mismatch | `-32000` |
| Env substitution | Missing variable | `-32000` |
| Connector execution | Query error | `-32000` |
| Handler execution | Script throws | `-32000` |
| Output transform | Script throws | `-32000` |
Error messages from scripts and connectors are included in the response. Stack traces are logged at debug level but not exposed to callers.
## Observability hooks
Each pipeline execution is instrumented with OpenTelemetry spans when tracing is enabled. Span attributes include tool name, execution stage, cache hit/miss, connector type, and duration. Sensitive values are redacted. See [Observability](/runtime/observability).