Summary

Severity: Medium
Area: Tools / schema
Affected files: agentkit/tools/schema.py:63-78
Suggested branch: fix/tool-schema-defs
Suggested PR title: fix(tools): preserve $defs in generated tool schemas

This is finding AUDIT-13 of 18 from a consolidated audit of agentkit/. It is deliberately self-contained so it can be fixed on its own branch with its own PR.

Related findings: Independent of the other findings.

AUDIT-13 — Medium — Tool JSON schemas drop $defs (unresolvable $ref)

File — agentkit/tools/schema.py:63-78

    raw_json_schema = args_model.model_json_schema()
    properties: dict[str, Any] = raw_json_schema.get("properties", {})
    required: list[str] = raw_json_schema.get("required", [])

    parameters: dict[str, Any] = {
        "type": "object",
        "properties": properties,
    }
    if required:
        parameters["required"] = required

Why this is a bug

Pydantic emits nested models and enums as $ref: "#/$defs/…", with the definitions in a sibling $defs key. The schema builder keeps only type/properties/required, so the $defs section is dropped and the emitted schema contains unresolvable references, which providers reject or mis-handle.

Reproduced

tool param typed as an Enum or a nested BaseModel
-> parameters = {"type":"object","properties":{"mode":{"$ref":"#/$defs/Mode", ...}}}
-> no "$defs" key in the emitted schema

Pass cases

• A tool whose parameters contain an Enum or a nested BaseModel produces a schema in which every $ref resolves inside the emitted document.
• $defs (and additionalProperties, title, default handling) are preserved in the emitted parameters.
• The emitted schema is valid JSON Schema: a test resolves all $refs (or validates it with a JSON-Schema validator) and asserts no dangling references.
• Existing simple tools (calculator, read_file, http_fetch, sql_readonly, web_search) produce byte-identical schemas to today (no regression for the built-ins).

Definition of done (per AGENTS.md)

• New/updated unit and integration tests covering the pass cases above, all passing (pytest).
• ruff check ., ruff format --check . and mypy agentkit clean.
• Docstrings updated where behaviour changed; docs/PROGRESS.md updated (status, PR link, commit count, notes).
• A new ADR in docs/DECISIONS.md if an architectural decision was made.
• Branch pushed and PR opened (never commit directly to main).

Baseline at the time of writing: pytest is green on main (all tests pass; tests/real/* skipped unless AGENTKIT_REAL_INFRA=1).