The AI Learning Hub Journal

Descriptions and Schemas the Model Actually Reads

The definition is prompt content the model actually readswording and schema shape selection and invocation — fix systematic misuse here before touching the system promptTHE TOOL THE AGENT LACKSfails cleanly — the agent cannot do the thing,says so, and you learn somethingTHE VAGUELY DESCRIBED TOOLconfident misuse, trusted because it returnedsomething — misdiagnosed as reasoning for monthsTHE BAR — a competent new engineer, with no access to the code, would use it correctly every timeTHE DEFINITION AS SENT — READ AS LANGUAGErefund_orderdescription: Refunds a settled order. Use once payment has settled. Not for pending orders — prefer cancel_order. Returns the refund id.arguments: order_id · "8-digit order number" amount · "minor units (pence)" reason · one of [duplicate, faulty, goodwill] required: order_id, amountSELECTION FIRST: WHEN, AND WHEN NOTit names the sibling to prefer in the adjacent caseTHEN USE: EFFECT, RETURN, PRECONDITIONSplus an example call where argument shapes are unobviousENUMS AND FORMATS, STATEDa free string invites invented values and formatsREQUIRED MARKED REQUIREDomission fails loudly at the boundary, not with a silent defaultVALIDATE BEFORE EXECUTING — RETURN THE CORRECTABLE ERROR"reason must be one of duplicate, faulty, goodwill" is fixable in one step. Fail the bar? Do not ship.
Descriptions and schemas are prompt content — write for selection first, enumerate and describe every field, and validate before executing

A Badly Described Tool Is Worse Than No Tool

This is worth stating plainly because it inverts the usual instinct to add capability. A tool the agent does not have produces a clean failure: it cannot do the thing, says so, and you learn something. A tool with a vague or subtly wrong description produces confident misuse — called in the wrong situations, called with plausible but incorrect arguments, and trusted because it returned something. The resulting failures present as reasoning problems and get investigated as reasoning problems, which is why they survive for months. Before adding a tool, ask whether you can describe it precisely enough that a competent new engineer with no access to the codebase would use it correctly every time. If not, either fix the description or do not ship the tool, because the version you are about to ship will produce work you cannot trust.

  • A missing tool fails cleanly; a misdescribed tool fails confidently
  • Misuse from bad descriptions presents as reasoning failure and gets misdiagnosed for months
  • The bar: a competent engineer with no code access would use it right every time
  • Failing that bar, fix the description or do not ship the tool

Write the Description for Selection, Then for Use

A description does two jobs and most only do the second. First it has to help the model decide whether this tool is the right one right now, which means it must state when to use this and, more valuably, when not to — including which sibling tool to prefer in the adjacent case. Then it has to support correct invocation: what the tool does to the world, what it returns, what it costs or how long it takes if that should influence choice, and any precondition that must hold. Include a short example call for anything with non-obvious argument shapes. Write it in plain declarative prose rather than terse notation, because it is read as language. And when you observe a systematic misuse in production, the description is the first place to fix it, ahead of the system prompt.

  • State when to use it and when not to, naming the sibling to prefer instead
  • Cover effect on the world, return shape, cost or latency if it should affect choice, preconditions
  • Include an example call wherever argument shapes are not obvious
  • Fix systematic misuse in the tool description before touching the system prompt

Schemas That Prevent the Argument Error

The second most common agent failure after choosing the wrong tool is choosing the right tool with wrong arguments, and the schema is where most of that is prevented. Enumerate wherever a value comes from a fixed set, because a free string invites invention. Describe every field, including the ones that look self-explanatory, since date and amount and id are exactly the fields that get filled with a plausible wrong format. Be explicit about formats and units in the field description rather than assuming a convention. Mark required fields as required rather than defaulting silently, so an omission fails loudly at the boundary instead of proceeding with an assumption. And validate before executing, returning a specific correctable error — the field expects one of these values and received that one — which the model can act on in a single step.

  • Enumerate fixed sets; free strings invite invented values
  • Describe every field, especially dates, amounts and identifiers
  • State formats and units explicitly rather than relying on convention
  • Validate before execution and return a specific, correctable message

Prefer slides, quizzes, and saved progress? Read this lesson in the library — free, no sign-up.