CH 03 · Building the Prompt · 08/12
Read as one pageReal code: the tool schema is rewritten per provider
The tools list in the PromptBuilder you just built is already the JSON you want to send. pi keeps one Tool and rewrites it for each provider, because the JSON on the wire is not the same shape.
function convertTools(
tools: Tool[],
compat: ResolvedOpenAICompletionsCompat,
): OpenAI.Chat.Completions.ChatCompletionTool[] {
return tools.map((tool) => {
const grammar = resolveGrammarConstrainedSampling(tool, compat.supportsOpenAIGrammarTools);
if (grammar) {
return {
type: "custom",
// ... (a grammar-constrained tool, not a JSON schema)
};
}
const strict = resolveJsonSchemaStrictSampling(tool, compat.supportsStrictMode !== false); // [1]
return {
type: "function", // [2]
function: {
name: tool.name,
description: tool.description,
parameters: getJsonSchemaToolParameters(tool, strict) as Record<string, unknown>,
// Only include strict if provider supports it. Some reject unknown fields.
...(compat.supportsStrictMode !== false && { strict: strict ?? false }), // [3]
},
};
});
}
Source: earendil-works/pi, packages/ai/src/api/openai-completions.ts (MIT)
Anthropic's Messages API gets a different object from the same Tool.
function convertTools(
tools: Tool[],
isOAuthToken: boolean,
supportsEagerToolInputStreaming: boolean,
supportsStrictTools: boolean,
cacheControl?: CacheControlEphemeral,
disablePreferredStrictTools = false,
): BetaTool[] {
// ... (an empty-tools guard)
return tools.map((tool, index) => {
// ... (decide strict mode, then build the schema this provider accepts)
return {
name: isOAuthToken ? toClaudeCodeName(tool.name) : tool.name, // [4]
description: tool.description,
...(supportsEagerToolInputStreaming ? { eager_input_streaming: true } : {}),
...(strict === true ? { strict: true } : {}),
input_schema: inputSchema, // [5]
// ... (a cache marker on the last tool only)
};
});
Source: earendil-works/pi, packages/ai/src/api/anthropic-messages.ts (MIT)
What to notice
- [1]
resolveJsonSchemaStrictSamplingreturns true only when this tool asked for JSON-schema sampling, this provider supports it, andmakeStrictJsonSchemacan rewrite the schema. That rewrite puts every property name inrequiredand setsadditionalPropertiesto false. An optional property that does not already allow null is wrapped asanyOfwith{type: "null"}. If the tool saidrequireand that rewrite is impossible, or this provider cannot do strict sampling, the call throws. Aprefertool that cannot be rewritten sends the original schema. - [2] The tool is nested under
type: "function"and afunctionobject. Your builder putsnamebesidetype, which is the Responses API shape. Chat Completions wants the extra nesting. - [3]
strictis added only when the provider accepts it. The comment on the previous line says some servers reject fields they do not know. - [4]
convertToolsmaps eachToolto oneBetaTool. The object in the excerpt is the per-tool return, and the function returns that array. When the call uses an OAuth token, pi also sends the Claude Code betasclaude-code-20250219andoauth-2025-04-20, andtoClaudeCodeNamerenames a tool to Claude Code's spelling when the lowercased name matches that list (readbecomesRead). The comment on that lookup calls this stealth mode. Any other name is left as it is. - [5] The field this converter fills is
input_schema. Unless strict mode is on, that value is onlytype,properties, andrequired. Copyingtool.parametersacross under the old nameparametersleavesinput_schemaunset.
Codex's ToolSpec type tag can also be namespace, tool_search, web_search, or custom. Your builder lists only functions.
Read it yourself: Open google-shared.ts and find export function convertTools. The comment above it says useParameters is for Cloud Code Assist with Claude models, where that API translates parameters into Anthropic's input_schema. Then read the serde rename on each variant in tool_spec.rs. You should see kinds your builder never constructs, starting with web_search.
Finished this idea?
Your learning progress stays in this browser.