Skip to slide
038 / 221

CH 03 · Tool Design · 11/18

Read as one page

Real code: Codex's update_plan schema leaves little to guess

Codex is OpenAI's open-source coding agent, written in Rust. update_plan is the tool the model calls to keep a short checklist for its current task. The schema is small, yet it uses almost every rule from the section above: an enum, required fields, field descriptions, and a ban on extra keys. Watch also for the one rule a schema cannot express. The // [4] inside the description string is added here. It is not part of the text the model receives.

pub fn create_update_plan_tool() -> ToolSpec {
    let plan_item_properties = BTreeMap::from([
        // ... (4 lines: "step", a string described as "Task step text.")
        (
            "status".to_string(),
            JsonSchema::string_enum( // [1]
                vec![json!("pending"), json!("in_progress"), json!("completed")],
                Some("Step status.".to_string()),
            ),
        ),
    ]);
    // ... (7 lines: the top-level properties, starting with an optional "explanation" string)
        (
            "plan".to_string(),
            JsonSchema::array(
                JsonSchema::object(
                    plan_item_properties,
                    Some(vec!["step".to_string(), "status".to_string()]), // [2]
                    Some(false.into()), // [3]
                ),
                Some("The list of steps".to_string()),
            ),
        ),
    ]);
    ToolSpec::Function(ResponsesApiTool {
        name: "update_plan".to_string(),
        description: r#"Updates the task plan.
Provide an optional explanation and a list of plan items, each with a step and status.
At most one step can be in_progress at a time. // [4]
"#
        .to_string(),
        strict: false, // [5]

Source: openai/codex, codex-rs/core/src/tools/handlers/plan_spec.rs (Apache-2.0)

What to notice

  1. [1] JsonSchema::string_enum builds a string field limited to the listed values. json! is a macro from the serde_json crate, the JSON library Rust projects usually use. It writes a JSON value inline. Some wraps an optional value and vec! builds a list. The schema lists exactly three statuses: pending, in_progress, and completed. Because strict is false, a model can still emit "done". Parsing then fails, and the model gets that error back.
  2. [2] ToolSpec::Function and ResponsesApiTool are the structs Codex uses to register one function tool. JsonSchema::object takes three things: the properties, the list of required keys, and whether extra keys are allowed. Every plan item must carry both a step and a status. BTreeMap is Rust's sorted map, so the properties come out in the same order every time.
  3. [3] Some(false.into()) sets additionalProperties to false: no surprise keys such as "priority". A few lines below this excerpt, the top-level object does the same and lists only plan as required, which is how explanation stays optional.
  4. [4] JSON Schema has no simple way to say "at most one item in this array may have this value", so that rule goes in the description. The handler in plan.rs does not check it either; the description is its only guard.
  5. [5] strict asks OpenAI's API to hold the arguments to the schema exactly. The comment on that field in codex-rs/tools/src/responses_api.rs says strict mode needs every property listed in required; explanation is optional, so this tool runs non-strict. Codex validates on its own side: plan.rs parses the arguments into Rust types, and a failure becomes FunctionCallError::RespondToModel("failed to parse function arguments: ..."), an error the model reads and can correct.

Read it yourself: open codex-rs/protocol/src/plan_tool.rs, the same shape as Rust types. For each rule in the hand-written schema, find the line that enforces it during parsing: #[serde(rename_all = "snake_case")] is how InProgress becomes "in_progress", and #[serde(deny_unknown_fields)] mirrors additionalProperties: false. Then open plan.rs and answer two questions: what text does the model get back on success, and what happens if it marks two steps in_progress?

Finished this idea?

Your learning progress stays in this browser.