tekvo
← All notes

Typed tools beat prompt-described tools

A short note on why we describe agent tools with schemas rather than sentences.

Tekvo Engineering3 min read

A tool described in prose is a suggestion. A tool described by a schema is a contract the runtime can enforce before the model’s output reaches anything real.

What changes when a tool is typed?

Validation moves out of the prompt and into code. Malformed arguments fail at the boundary with a structured error the agent can act on, instead of reaching the system of record and failing somewhere expensive.

Does it hurt model performance?

In our evals it helps. Narrow, non-overlapping schemas cut tool-call fan-out, because the model stops hedging between two tools that could both plausibly answer the question.

What is the rule?

One tool, one job, one schema, one permission. If you find yourself writing “use this tool when…” in a description, that is usually two tools.

Still running the business on software from the dinosaur age?

Two-week scoping sprint, fixed fee, priced for a mid-size company. You keep the architecture either way.

Let's talk