Structured Tool Schemas in the Harness

Most advice about the agent tool schema is wrong about the most important thing it does. Guides treat the schema as a validation contract — a way to check that the model sent the right types — and stop there. But the schema is read by the model before it produces anything, which makes it the single most direct lever you have over what the model even attempts. The schema isn't mainly a validator. It's a prompt with a rigid structure, and the teams that get the most out of tools are the ones who write it that way.

Here's the contrarian claim stated plainly: your tool descriptions and field constraints shape the model's behavior more reliably than half the sentences in your system prompt, because the model reads them at the exact moment it's deciding how to call the tool. Treat the schema as an afterthought and you're leaving your most precise control unused.

What Is an Agent Tool Schema?

An agent tool schema is the structured definition of a tool the model can call — its name, its description, and the typed parameters it accepts, usually expressed as JSON Schema. The model receives these definitions and uses them to decide which tool to call and with what arguments. It's the interface between the model's intentions and your code's execution.

The part people underweight is that every word of it is input to the model. The description isn't documentation for your teammates; it's instruction for the model. The field names aren't just keys; they're hints about meaning. The constraints aren't just validation; they're a menu the model chooses from. A well-written schema tells the model how to behave without a single line in the prompt.

send_email = {
    ,[object Object],: ,[object Object],,
    ,[object Object],: ,[object Object],
                   ,[object Object],
                   ,[object Object],,
    ,[object Object],: {
        ,[object Object],: ,[object Object],,
        ,[object Object],: {
            ,[object Object],: {,[object Object],: ,[object Object],, ,[object Object],: ,[object Object],},
            ,[object Object],: {,[object Object],: ,[object Object],, ,[object Object],: ,[object Object],},
            ,[object Object],: {,[object Object],: ,[object Object],, ,[object Object],: [,[object Object],, ,[object Object],]},
        },
        ,[object Object],: [,[object Object],, ,[object Object],],
    },
}

What this does: Defines a

send_email

enum

maxLength

Why It Matters

The schema is where you convert vague intentions into hard constraints. "The model should only pick one of these categories" is a wish in a prompt and a guarantee in an

enum

This matters because prompt instructions degrade under pressure. A long conversation, a confusing user request, an injection in a document — any of these can push a prompt instruction out of the model's effective attention. A schema constraint doesn't degrade the same way, because it's presented fresh with every tool-call decision and it defines the shape of a valid response. You're constraining the output space, not just requesting good behavior within it.

⚡ Pro tip: Move every "the model must choose from X, Y, or Z" rule out of your prompt and into an

enum

Writing Schemas the Model Actually Uses Well

The highest-value work is in the descriptions and constraints, so treat them as carefully as you'd treat prompt copy.

Write field descriptions that answer the question the model is about to ask itself. For a

date

Use constraints to make invalid states unrepresentable. A

minimum

maximum

pattern

maxItems

[object Object],: {
    ,[object Object],: ,[object Object],,
    ,[object Object],: ,[object Object],,
    ,[object Object],: ,[object Object],,
    ,[object Object],: ,[object Object],
                   ,[object Object],
}

What this does: Constrains refunds to the 0–500 range structurally and tells the model, in the description, why the ceiling exists and what to do instead. The model gets both the hard limit and the reasoning, so it doesn't just fail at 501 — it knows to route large refunds elsewhere. Constraint plus explanation is far stronger than either alone.

⚠️ Common mistake: Making every field a free-form string because it's easy. A string field invites the model to put anything in it, which means you validate everything downstream and still get surprises. Every field you can express as an enum, a bounded number, or a pattern is a field the model can't get creatively wrong. Reach for the tightest type the data allows, always.

Generating Schemas From Types

Hand-writing JSON Schema is tedious and drifts from your actual code. A better pattern is to define the tool's input as a typed model and generate the schema from it, so the schema and the validation are the same source of truth.

[object Object], pydantic ,[object Object], BaseModel, Field

,[object Object], ,[object Object],(,[object Object],):
    to: ,[object Object], = Field(description=,[object Object],)
    subject: ,[object Object], = Field(max_length=,[object Object],)
    priority: ,[object Object],[,[object Object],, ,[object Object],] = ,[object Object],

schema = SendEmail.model_json_schema()   ,[object Object],

What this does: Defines the tool's inputs once as a Pydantic model and derives the JSON Schema from it. The

Literal

max_length

Helping the Model Pick the Right Tool

Argument shape is only half of what a schema controls; the other half is selection — which tool the model reaches for in the first place. When an agent has fifteen tools and picks the wrong one, the cause is almost always overlapping or vague descriptions, and the fix lives in the schema, not the prompt.

The trick is to write each tool's description to answer "when should I use this one instead of the similar-looking one next to it?" If you have

search_docs

search_tickets

[object Object],: (,[object Object],
                ,[object Object],
                ,[object Object],)

What this does: Tells the model not just what the tool does but when not to reach for it and where to go instead. That cross-reference to

modify_subscription

⚡ Pro tip: If your agent keeps confusing two tools, don't add a prompt rule telling it which to use — sharpen the two descriptions so the boundary between them is unmistakable. Prompt rules about tool choice compete with everything else in the prompt for attention; a clear description is read at the exact moment the choice is being made. Fix it at the point of decision.

Watch total schema size, too. Every tool definition is tokens in the model's context on every single call, and a sprawling set of rarely-used tools both costs money and dilutes the model's attention across options it'll almost never need. If a tool is used in under 1% of runs, consider whether it belongs in the always-loaded set or should be gated behind a smaller, task-specific tool list.

Common Mistakes

The mistake underneath all the others is treating the schema as machine plumbing the model doesn't really read. It reads every character. A vague description produces vague behavior; a precise one produces precise behavior. Invest in the words.

The second is over-describing the tool and under-constraining the fields. Teams write a three-paragraph tool description and then leave every parameter as an unbounded string. Flip that ratio — a tight description and tightly typed fields do more than a verbose description and loose fields ever will.

The third is forgetting that the schema is advisory to the model and mandatory only if you enforce it. The model usually respects your constraints, but "usually" isn't "always," which is why the schema is the first layer and hard validation at the execution boundary is the second. The schema shapes behavior; it doesn't guarantee it.

Conclusion

An agent tool schema is your most direct, most reliable control over how the model uses tools — not because it validates types, but because the model reads it at the moment of decision. Write descriptions like prompt copy, encode every fixed choice as an enum, constrain every field to the tightest type its data allows, and generate the schema from typed code so it never drifts. Do that and a surprising amount of behavior you were trying to enforce in the prompt just... happens, by construction.

Because good schemas are hard-won and easy to lose, keep them versioned alongside the prompts they work with in a library like PromptABCD, so the schema you tuned across a dozen edge cases is the exact one your next agent reuses — descriptions, enums, constraints, and all.