Grok Build · Cross-Tool Normalization

Canonical Input Is a Stable Projection

Different harnesses can use different raw parameter names. Grok Build projects a small set of stable semantics into x.ai/tool metadata, giving presentation, telemetry, and cross-tool analysis a shared vocabulary.

Learning Objective Memorize the eight canonical fields, the seven CanonicalToolMeta fields with version = 1, and be able to explain why input may have missing fields or be omitted entirely.
Core Visual · Teaching Projection Diagram
raw_input Afile_path · old_stringnew_string · replace_all raw_input Bpath · offset · limitother harness fields canonicalprojection x.ai/tool · version 1name · kind · namespace · labelread_onlyinput: { path, offset, limit }Only stable, lightweight cross-fields retained
Teaching diagram: projection may discard fields; the full raw input is still carried by raw_input.
Eight Canonical Fields
path

File or search path

offset

Normalized start position

limit

Read or result limit

command

Command to execute

description

Command description

cwd

Working directory vocabulary

directory

Directory listing target

pattern

Search pattern

Metadata Contract and Omission Rules

Actual Fields of CanonicalToolMeta

versionnamekindnamespacelabelread_onlyinput

version is the number 1. input is an optional JSON value and is omitted entirely when there is no stable projection.

input Stays Lightweight

It is a canonical projection, not a mirror of raw input. Non-shared fields like grep flags and replace_all may be discarded; large fields such as before/after edit text and full write content do not enter the projection and can be obtained from raw_input.

Public Behavior Comparison: The Read tool in Claude Code's public documentation uses file_path, offset, and limit. Grok Build's normalization layer maps its own tool inputs to shared fields such as path. This comparison only covers publicly visible tool input naming and does not infer Claude Code's internal implementation.
Source Code Evidence
crates/codegen/xai-grok-tools/src/tool_taxonomy.rs · Lines 12–30, 190–200
pub mod field {
    pub const PATH: &str = "path";
    pub const OFFSET: &str = "offset";
    pub const LIMIT: &str = "limit";
    pub const COMMAND: &str = "command";
    pub const DESCRIPTION: &str = "description";
    pub const CWD: &str = "cwd";
    pub const DIRECTORY: &str = "directory";
    pub const PATTERN: &str = "pattern";
}
pub const TOOL_META_VERSION: u32 = 1;

pub struct CanonicalToolMeta {
    pub version: u32,
    pub name: String,
    pub kind: ToolKind,
    pub namespace: ToolNamespace,
    pub label: Cow<'static, str>,
    pub read_only: bool,
    pub input: Option<serde_json::Value>,
}
Source Snapshot Note: Based on the local repository at grok-build-main, files xai-grok-tools/src/tool_taxonomy.rs and normalization.rs, verified on 2026-07-17. No content canonical field exists in the source; fictitious metadata fields and version examples from older pages have been removed.
Classroom Exercise
04

Create a Projection for an Edit Call

The raw input contains file_path, old_string, new_string, and replace_all. Write out the canonical input and identify which fields should remain in raw_input.

Takeaway: The canonical layer pursues stable shared semantics across harnesses. The current fields are only path/offset/limit/command/description/cwd/directory/pattern, and the metadata version is the number 1. input may omit sensitive or large fields.