Canonical Input Is a Stable Projection
Using CanonicalToolMeta and input projection to explain stable contracts across tool implementations
THE QUESTION THIS PAGE ANSWERS
ANSWER FIRSTWhat is the key idea behind “Canonical Input Is a Stable Projection”?
Using CanonicalToolMeta and input projection to explain stable contracts across tool implementations
Make the claim earn its place. Use this page as a decision aid, not a definition to memorize. Connect the idea to one real task, one observable result, and one failure that would change your mind.
Write one question you could answer with evidence after trying this idea.
A conclusion that sounds complete but leaves the key assumption untested.
CanonicalToolMeta fields with version = 1, and be able to explain why input may have missing fields or be omitted entirely.
pathFile or search path
offsetNormalized start position
limitRead or result limit
commandCommand to execute
descriptionCommand description
cwdWorking directory vocabulary
directoryDirectory listing target
patternSearch pattern
Actual Fields of CanonicalToolMeta
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.
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.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>,
}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.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.
path/offset/limit/command/description/cwd/directory/pattern, and the metadata version is the number 1. input may omit sensitive or large fields.
The handoffs inside “Core Visual · Teaching Projection Diagram”
“version is the number 1.” shows that an Agent is not defined by the model alone. Each handoff between model, context, tools, state, permissions, and people affects both progress and recovery.
Write the state before adding capability
Starting from “It is a canonical projection, not a mirror of raw input.”, split the workflow into starting state, next action, tool result, state update, and stop condition. Debugging then means finding the first lost piece of information or authority instead of saying vaguely that the model “got worse”.
A happy path is not reliability
Use “The raw input contains file_path , old_string , new_string , and replace_all .” to replay one successful and one failed run. Record the context, tool result, and owner at each turn; the workflow is maintainable when a second person can follow it without the original builder.
From “Core Visual · Teaching Projection Diagram” to “Eight Canonical Fields”
“Core Visual · Teaching Projection Diagram” grounds the problem in “raw_input A file_path · old_string new_string · replace_all raw_input B path · offset · limit other harness fields canonical projection x.ai/tool · version 1 name · kind · namespace · label read_only input: { p…”. “Eight Canonical Fields” then moves it toward “Normalized start position”. Together, they show that the lesson is not just a conclusion to remember, but a claim with conditions.
Carry the judgment into the next situation
When analyzing an Agent, trace state, action, tool result, and next step in order. Each handoff should explain where information came from, who confirmed it, and where failure stops.
- “Core Visual · Teaching Projection Diagram”: raw_input A file_path · old_string new_string · replace_all raw_input B path · offset · limit other harness fields canonical projection x.ai/tool · version 1 name · kind · namespace · label read_only input: { p…
- “Eight Canonical Fields”: Normalized start position
- “The closing point”: 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
The final “The closing point” brings the discussion to “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 ”. The useful thing to carry forward is knowing which judgments must be revisited when input, scale, or risk changes.
I turned one judgment from this article into a small experiment I could run today. Knowing what to observe next is more useful than simply remembering the conclusion.
After reading this, I first looked for the conditions behind the idea instead of copying the method into a project. That order made the later trade-offs much clearer.
When this judgment reaches real work, which constraint should be added first? I am curious which step matters most between reading and the first practical attempt.
No discussion on this article yet.