Tool Schema Design Is the Real Agent Framework Decision

The failure mode nobody budgets for

Most teams pick an agent framework first. They compare LangGraph to the OpenAI Agents SDK to CrewAI, run a spike, pick a winner, and start building. Six weeks later the agent works in demos and fails in production — not because the orchestration graph was wrong, but because the model keeps calling get_data when it should call search_orders, or passes a free-text date string where the downstream API expects ISO 8601.

The framework was never the problem. Tool schema design — not the framework — determines whether an AI agent behaves reliably.

This is the decision most teams make implicitly and get wrong. Framework choice gets a two-week evaluation; tool schema design gets whatever falls out of the first sprint. But frameworks are execution layers. They handle control flow, retries, memory, and tracing, and they are increasingly interchangeable. Tool schemas are the interface between a probabilistic model and deterministic systems. They are the durable, portable asset — the thing you'll carry across every framework migration for the next three years.

The asymmetry is stark. A framework swap is a bounded engineering task with a known surface area: the orchestration code. A schema rewrite is unbounded, because every prompt, every evaluation case, every downstream integration, and every cached trace depends on the shape of your tool contracts. Teams routinely discover this in reverse: they migrate frameworks expecting the hard part to be the graph, and find that the graph was a weekend and the tool layer is a quarter.

This article covers why framework choice is downstream of schema design, what a well-designed tool schema actually looks like, the patterns that survive framework swaps, how schema quality shows up in production metrics, and a checklist to run before you commit to a framework. (See also: [how to evaluate an AI agent framework](internal-link: agent-framework-evaluation-guide).)

Why framework choice is downstream of schema design

Function calling has converged. OpenAI, Anthropic, Google, and the major open-weight models all accept JSON-schema-style tool definitions with names, descriptions, and typed parameters. The transport differs slightly; the contract does not. A tool schema written well for one provider carries across to another with a short, predictable list of adjustments — not a rewrite.

That convergence changes the economics of the framework decision. If the schema is solid, the framework is a swappable runtime. If the schema is sloppy, no framework will save you — better retry logic just means the model confidently calls the wrong tool more times.

The framework migration trap

Here's the pattern we see repeatedly. A team builds 20 tools inside a framework's abstraction — decorators, Pydantic models, framework-specific tool registries. Two years later they migrate, and the orchestration rewrite takes two sprints while the tool layer takes two quarters, because the schemas were never cleanly separated from the framework's plumbing.

The trap has a specific anatomy. The schemas look portable because they're expressed as Python types or TypeScript interfaces. But the meaning lives in the framework's conventions: how it injects context, how it serializes return values, how it maps exceptions to model-visible errors, how it truncates long outputs. None of that is in the type signature. When you migrate, the types come along and the semantics don't, so every tool has to be re-validated against the new runtime's behavior — which is functionally a rewrite.

Framework lock-in is real, but schema lock-in is avoidable. The fix is architectural: define tool schemas as standalone artifacts — versioned JSON Schema or equivalent — and let the framework adapt to them, not the reverse. In practice this means a thin adapter layer: your canonical schema file is the source of truth, and each framework gets a small, disposable translation module that registers tools from that file. The adapter is the thing you throw away on migration; the schema is the thing you keep. (Related: [designing portable tool contracts for LLM agents](internal-link: portable-tool-contracts).)

What actually ports between frameworks

Ports cleanly: tool names, descriptions, input schemas, output contracts, error shapes, enum values, and required-field declarations.
Ports with edits: $ref resolution and additionalProperties/strict-mode behavior, oneOf/anyOf support, format keyword honoring (many providers ignore it at validation time), and any provider-specific extension fields (for example OpenAI's strict flag or Gemini's functionDeclarations subset). Test these against each target provider rather than assuming.
Does not port: chaining abstractions, memory implementations, agent-to-agent handoff patterns, control-flow graphs, and framework-specific callback hooks.

The first two lists are where agent reliability lives. The third is where framework churn lives. Invest your design effort accordingly. A practical rule: if a design decision changes how the model behaves, it belongs in the schema layer and must port. If it changes how the runtime executes, it belongs in the adapter and can be thrown away.

The model never sees your framework. It sees your tool names, descriptions, and parameter schemas. That's the entire surface area of the decision it's making.

What a well-designed tool schema looks like

A good tool schema is a prompt. It is read by the model at inference time, on every turn, and it competes for attention with the system prompt and the conversation. Treat it with the same care you'd give a production prompt — because that's what it is. (See: [prompt engineering best practices for tool use](internal-link: prompt-engineering-tool-use).)

Descriptions as prompts: naming, intent, and boundaries

Tool and parameter descriptions are instructions, not documentation. Write them for a model that has never seen your codebase.

Naming: verb-noun, unambiguous, scoped. search_orders beats get_data. create_refund beats process. If two tools could plausibly be confused, rename one until they can't. Names are the cheapest signal you have, and they're read before descriptions.
Intent: state what the tool does and when to use it. "Retrieves order records by customer ID or date range. Use this when the user asks about order history or status. Do not use for refunds — use create_refund."
Boundaries: explicitly name the adjacent tool the model should prefer for a near-miss case. Negative guidance is cheap and, in our experience, one of the highest-leverage edits you can make to reduce wrong-tool calls. Measure it: track wrong-tool rate before and after adding boundary guidance to confirm the effect on your workload.

A concrete before-and-after shows the difference better than any principle. Weak:

{
  "name": "get_data",
  "description": "Gets data from the system.",
  "parameters": {
    "type": "object",
    "properties": {
      "query": { "type": "string" },
      "date": { "type": "string" }
    }
  }
}

Strong:

{
  "name": "search_orders",
  "description": "Retrieves order records filtered by customer ID or date range. Use when the user asks about order history, delivery status, or order totals. Do not use for refunds or cancellations — use create_refund or cancel_order instead.",
  "parameters": {
    "type": "object",
    "properties": {
      "customer_id": { "type": "string", "description": "Internal customer UUID, format 8-4-4-4-12." },
      "start_date": { "type": "string", "format": "date", "description": "ISO 8601 date (YYYY-MM-DD), inclusive." },
      "end_date": { "type": "string", "format": "date", "description": "ISO 8601 date (YYYY-MM-DD), inclusive. Must be on or after start_date." }
    },
    "required": ["customer_id"]
  }
}

The second version costs more tokens and earns them: it removes the ambiguity that produces wrong-tool calls and malformed arguments.

Input contracts: types, enums, and required fields

Every free-text string is a place the model can hallucinate. Constrain aggressively.

Enums over free strings. status: "shipped" | "pending" | "cancelled" instead of status: "string". The model can't invent a fourth value.
Required fields, deliberately. Mark only fields the tool genuinely cannot run without. Over-requiring fields forces the model to guess; under-requiring them pushes validation downstream into runtime errors.
Format constraints. Specify ISO 8601 dates, E.164 phone numbers, UUID formats. In practice the model follows explicit format hints far more reliably than it infers them from field names — treat this as a design heuristic and validate at the boundary regardless.
Shallow nesting. Deeply nested objects tend to raise argument-construction error rates. Flatten where possible; if you need structure, keep it one level deep. Validate the assumption against your own argument-validation telemetry.

A common failure mode here is the "kitchen sink" tool: one update_record that takes a free-form object and applies whatever fields are present. It's convenient for developers and disastrous for models, because the schema communicates nothing about which fields are valid together or what the valid values are. Prefer several narrow, enum-constrained tools over one polymorphic tool; the model's job is selection, and selection is easier when the options differ in kind rather than in an untyped payload.

Budget your tool surface

Tool definitions consume context on every turn, and tool-selection accuracy tends to degrade as the number of simultaneously available tools grows. Two design rules follow:

Keep the per-turn tool set small. If you have 40 tools, don't expose 40 to every turn. Route by intent — a retrieval or allow-list step that surfaces the 5–10 relevant tools — so the model chooses among a small, high-signal set.
Watch description length. Descriptions earn their tokens, but a 300-token description on every tool in a 30-tool set is a large recurring cost. Keep the operative instruction tight; push exhaustive detail into a linked reference the model can fetch when needed.

Structured outputs and error semantics

What comes back matters as much as what goes in. Define a return schema so the model can reason over the result instead of parsing prose. Return typed, stable fields — not a serialized log line. A tool that returns "Order 4471 shipped 2024-03-02" forces the model to re-parse text it will likely misread; a tool that returns {"order_id": "4471", "status": "shipped", "shipped_on": "2024-03-02"} gives it fields it can cite, filter, and pass to the next tool.

Errors deserve the same treatment. An error payload is an instruction to the model, so make it one:

{
  "error_code": "INVALID_DATE_RANGE",
  "retryable": true,
  "message": "start_date must be on or before end_date.",
  "suggestion": "Swap the dates or ask the user to confirm the range."
}

Distinguish retryable from terminal. A transient timeout is retryable; a malformed argument is not — it needs a corrected call. Encode this explicitly so the agent doesn't blindly retry a deterministic failure.
Never surface raw stack traces or internal IDs. They consume tokens and teach the model nothing actionable.
Make the correction path obvious. The suggestion field is where you steer the next attempt.

The failure mode to avoid is the opaque error. A tool that returns {"error": "500"} or a bare exception string gives the model no information about whether to retry, reformulate, or escalate to the user — so it usually retries, sometimes indefinitely. A typed error envelope converts a dead end into a next step.

How schema quality shows up in production metrics

Schema design is measurable. Instrument these and attribute them to schema changes:

Metric	What it reveals	Schema lever
Wrong-tool rate	Model selects an adjacent tool	Naming, boundary guidance
Argument-validation failure rate	Bad types, formats, missing fields	Enums, required fields, format hints
Retry rate per tool	Ambiguous errors or flaky contracts	Error envelope, retryable flag
Tool-selection latency	Oversized tool surface	Per-turn allow-listing
Tokens per turn (tool defs)	Bloated descriptions	Description budget

Wire these into your tracing from day one. When a schema edit moves the wrong-tool rate, you'll know — and you'll have evidence for the next framework decision instead of a demo. Two measurement practices make the data trustworthy. First, tag traces with a schema version so you can compare before and after a change on the same workload rather than across weeks of drifting traffic. Second, hold a small regression set of realistic user requests that exercise near-miss tool pairs; run it on every schema change and every provider or model upgrade. The regression set is what turns schema design from taste into engineering.

Checklist: run this before you commit to a framework

If the schemas pass this checklist, the framework is a runtime detail you can change later. If they don't, no framework will rescue the agent — and the migration you're about to plan will cost two quarters instead of two sprints.