Skip to slide
031 / 170

CH 03 · Building the Prompt · 08/12

Read as one page

Real 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. [1] resolveJsonSchemaStrictSampling returns true only when this tool asked for JSON-schema sampling, this provider supports it, and makeStrictJsonSchema can rewrite the schema. That rewrite puts every property name in required and sets additionalProperties to false. An optional property that does not already allow null is wrapped as anyOf with {type: "null"}. If the tool said require and that rewrite is impossible, or this provider cannot do strict sampling, the call throws. A prefer tool that cannot be rewritten sends the original schema.
  2. [2] The tool is nested under type: "function" and a function object. Your builder puts name beside type, which is the Responses API shape. Chat Completions wants the extra nesting.
  3. [3] strict is added only when the provider accepts it. The comment on the previous line says some servers reject fields they do not know.
  4. [4] convertTools maps each Tool to one BetaTool. 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 betas claude-code-20250219 and oauth-2025-04-20, and toClaudeCodeName renames a tool to Claude Code's spelling when the lowercased name matches that list (read becomes Read). The comment on that lookup calls this stealth mode. Any other name is left as it is.
  5. [5] The field this converter fills is input_schema. Unless strict mode is on, that value is only type, properties, and required. Copying tool.parameters across under the old name parameters leaves input_schema unset.

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.