Tool Calling & Schema Translation
Relevant source files
The following files were used as context for generating this wiki page:
- src/upstream/signals/AGENTS.md
- src/upstream/signals/tool-name-map.ts
- src/upstream/foreign-client-signals.ts
- cli-bridge/lib/tool-map.ts
- test/suites/entries/verify/tool/param/dispatch-ready.ts
- src/upstream/signals/mcp-names.ts
- test/suites/entries/verify/tool/name-mapping.ts
- test/suites/entries/verify/tool/restore-declared.ts
The Tool Calling and Schema Translation system manages the transformation of tool identities and parameters between downstream clients (such as Claude Code, Cursor, or specialized agents) and the upstream official client. The system ensures that downstream tool calls are mapped to official equivalents for compatibility while maintaining the ability to restore original client tool names and parameter structures in responses.
This module acts as the unique translation layer for the project. It handles incoming requests by replacing downstream tool names with official ones and outgoing responses by restoring the official names back to their downstream counterparts. It also performs parameter translation to align field names, types, and constraints required by different client schemas.
Sources: src/upstream/signals/AGENTS.md:6-12, src/upstream/foreign-client-signals.ts:167-175
Architecture and Data Flow
The translation process operates in two primary directions: downstream-to-upstream (Downlink) and upstream-to-downstream (Uplink).
Downlink Translation (Request)
When a client sends a request, the system maps downstream tool names to official upstream tool names. This mapping allows the model to recognize tools using official semantics and billing structures. Tools without official equivalents are carried via the MCP (Model Context Protocol) carrier channel to avoid semantic loss.
Uplink Translation (Response)
When the upstream returns a tool_call, the system performs the reverse mapping. It restores the official tool name to the specific name declared by the client in the current request. This prevents "unknown tool" errors in clients that do not recognize official upstream internal names.
This diagram illustrates the bidirectional flow of tool name mapping and parameter translation between the client and the official upstream.
Sources: src/upstream/signals/AGENTS.md:9-12, src/upstream/signals/tool-name-map.ts:18-23, src/upstream/foreign-client-signals.ts:178-185
Key Components and Logic
Tool Name Mapping
The system maintains a centralized source of truth for name mapping. A critical requirement is that the Node.js mapping table and the Bun-based CLI bridge mapping table must remain identical to ensure consistency across different protocol paths.
| Table/Function | Description |
|---|---|
CLIENT_TO_OFFICIAL_TOOL | The primary downlink mapping from downstream names to official ones. |
OFFICIAL_NATIVE_TO_CLIENT | A supplementary uplink table mapping official native names to downstream tools (e.g., suggest_prompts to ask_user_question). |
buildOfficialToClientMap | Constructs the reverse mapping table filtered by the tools declared in the current request. |
Sources: src/upstream/signals/AGENTS.md:20-22, src/upstream/signals/tool-name-map.ts:26-30, src/upstream/signals/tool-name-map.ts:85-88
Parameter Translation Engine
Parameter translation modifies fields to match downstream schemas. This includes renaming keys, converting types (e.g., seconds to milliseconds), and synthesizing required fields that are absent in the official response.
- Field Synthesis: If a downstream schema requires a field that the official upstream does not provide (e.g.,
bashrequires adescription), the engine generates it to prevent schema validation failures. - Mandatory Cropping: Since downstream clients often set
additionalProperties: false, the engine must prune any extra official keys that the downstream client does not recognize. - Declared Filtering: The system only restores tools that were explicitly declared in the current request's
toolsarray to avoid creating "phantom" tools the client cannot handle.
Sources: src/upstream/signals/AGENTS.md:26-32, test/suites/entries/verify/tool/restore-declared.ts:12-16
Implementation Details
Parameter Rules and Constraints
Translation rules are defined to handle specific behavioral differences. For instance, the official timeout_seconds: -1 (unlimited) must be handled carefully, as downstream schemas might only accept positive integers for timeoutMs.
// Example of parameter translation logic for bash tools
// Sources: [test/suites/entries/verify/tool/param/dispatch-ready.ts:107-115]
for (const [raw, expectMs] of [['-1', undefined], ['0', undefined], ['1', 1000]]) {
const r = dispatch('run_terminal_command', `{"command":"x","timeout_seconds":${raw}}`)
// Validates that -1 or 0 result in undefined (unlimited/default)
// while positive values are converted to milliseconds.
}
Sources: test/suites/entries/verify/tool/param/dispatch-ready.ts:107-115, src/upstream/signals/AGENTS.md:34-36
MCP Tool Carrying
For tools without official equivalents, the system uses an MCP carrier server named proxy. This synthesizes an exposed tool name using the format server__tool. If the resulting name violates official naming constraints (1-64 characters, alphanumeric), the system cleans the name and appends a SHA-256 hash prefix.
The diagram shows how tools are routed either through official mappings or the MCP carrier based on the existence of an official equivalent.
Sources: src/upstream/signals/mcp-names.ts:31-40, src/upstream/signals/mcp-names.ts:50-58
Validation and Testing
The project implements rigorous verification suites to ensure translation integrity:
- Consistency Check:
test/suites/entries/verify/tool/name-mapping.tsensures Node and Bun mapping tables are synchronized. - Dispatch Readiness:
test/suites/entries/verify/tool/param/dispatch-ready.tsverifies that official tools can be successfully dispatched to downstream clients in a single pass. - Idempotency: The system ensures that applying restoration multiple times does not further change the tool names or arguments.
Sources: src/upstream/signals/AGENTS.md:65-70, test/suites/entries/verify/tool/name-mapping.ts:18-26, test/suites/entries/verify/tool/param/dispatch-ready.ts:14-22
The Tool Calling & Schema Translation module is critical for maintaining high compatibility across diverse AI agents while leveraging official upstream model capabilities without triggering foreign client detection or schema validation errors.