The Tool System and Event-Driven Design: Parameter Validation, Feeding Errors Back for Self-Correction, Event Subscription (dg P05/P06/M05/M07)
Make the tool system solid: validate parameters, feed errors back to the model so it can correct itself, then use event subscription to expose the agent's internal state to an outside interface.
Today's Goals
- Add parameter validation to every tool, rejecting invalid input with a readable error
- Design a mechanism that lets the model see an error and correct its own call arguments
- Subscribe to the agent's event stream, outputting progress or typing status in real time
Yesterday closed on this: D4's fallback handles unreliable external services, and today's error feedback handles the model's own mistakes. A provider going down means switching vendors; a model filling an argument in wrong is nobody else's fault, and all you can do is let it try again. D2's tools were good enough to run; today they become tools that do not crash, that self-correct when they do, and that are visible from outside.
Plain-Language Walkthrough
A map of your tools: format constraints, cross-references, and the cost of a rename
Ordering from an online store, whether you buy the right item rests entirely on the title and the spec table: "multi-purpose storage box" leaves you guessing whether A4 paper fits, while "32 cm internal width" is something you can order from with confidence. A model picking a tool is in exactly that position โ D2 established that floor, and today we nail down the three ways of writing a definition that most often go wrong.
One, format fields with no valid example. The model has no concept of what an order number looks like, so it invents one by feel. Adding "for example SO20260901" is the highest-return line in the whole definition. Then write the same constraint into the schema as a pattern regex โ sent to the model it is a manual, and kept for the next section's validator it is a rule, and growing both from one place means they cannot drift apart.
Two, D2 said to write down when to use and when not to use a tool, without saying how โ the answer is cross-references between tools. The most valuable part of a description is often the negative space. Say only "look up an order" and the model will reach for it to look up refunds and shipping too; add "looks up the order itself only; use track_shipment for shipping events and query_refund for refund progress" and misuse drops by more than half immediately. The more tools you have, the less you are writing separate manuals and the more you are drawing a map of your tools.
Three, treating a tool name as a function name you may refactor on a whim. D2 said the name should read like a command; what it did not say is what the name becomes after launch โ a tool name is an external contract.
// A tool definition is part of the prompt: this text enters the model's context verbatim
export const queryOrder = {
name: 'query_order',
description:
'Look up one order status, amount and creation time by order number. ' +
'Looks up the order itself only; use track_shipment for shipping events ' +
'and query_refund for refund progress.',
parameters: {
type: 'object',
properties: {
order_id: {
type: 'string',
description: 'Order number, SO followed by 8 digits, for example SO20260901',
pattern: '^SO\\d{8}$',
},
},
required: ['order_id'],
},
}# A tool definition is part of the prompt: this text enters the model's context verbatim
QUERY_ORDER = {
"name": "query_order",
"description": (
"Look up one order status, amount and creation time by order number. "
"Looks up the order itself only; use track_shipment for shipping events "
"and query_refund for refund progress."
),
"parameters": {
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "Order number, SO followed by 8 digits, for example SO20260901",
"pattern": r"^SO\d{8}$",
},
},
"required": ["order_id"],
},
}// Dependencies: Jackson. Writing the schema as a text block avoids escaping hand-built JSON.
// One ToolSpec carries everything: the first three fields are the manual sent to the model
// and execute is the local implementation, so the next section's runTool reads the
// implementation straight off it without maintaining a separate name-to-function map
@FunctionalInterface
interface ToolImpl {
String apply(JsonNode args);
}
record ToolSpec(String name, String description, JsonNode parameters, ToolImpl execute) {}
static final ObjectMapper MAPPER = new ObjectMapper();
static ToolSpec queryOrder() throws JsonProcessingException {
var schema = MAPPER.readTree("""
{
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "Order number, SO followed by 8 digits, for example SO20260901",
"pattern": "^SO\\\\d{8}$"
}
},
"required": ["order_id"]
}
""");
return new ToolSpec(
"query_order",
"Look up one order status, amount and creation time by order number. "
+ "Looks up the order itself only; use track_shipment for shipping events "
+ "and query_refund for refund progress.",
schema,
args -> queryOrderById(args.get("order_id").asText()));
}// In Swift the schema is an Encodable type too, so a misspelled field name is caught at compile time
struct ParameterSpec: Encodable {
let type: String
let description: String
var pattern: String?
// Lower and upper bounds for integer parameters, used by D12's memory_search. Encodable
// skips nil automatically, so adding optional fields here does not change the schema
// that existing tools encode to
var minimum: Int?
var maximum: Int?
}
// One ToolSpec carries everything: the manual and the local implementation hang off the same
// type, so the next section's runTool reads execute straight off it. CodingKeys omits execute,
// so encoding skips it and only the first three fields enter the request body
struct ToolSpec: Encodable {
let name: String
let description: String
let parameters: ObjectSchema
let execute: ([String: JSONValue]) async -> String
enum CodingKeys: String, CodingKey {
case name, description, parameters
}
struct ObjectSchema: Encodable {
let type = "object"
let properties: [String: ParameterSpec]
let required: [String]
}
}
let queryOrder = ToolSpec(
name: "query_order",
description: """
Look up one order status, amount and creation time by order number. \
Looks up the order itself only; use track_shipment for shipping events \
and query_refund for refund progress.
""",
parameters: .init(
properties: [
"order_id": ParameterSpec(
type: "string",
description: "Order number, SO followed by 8 digits, for example SO20260901",
pattern: "^SO\\d{8}$")
],
required: ["order_id"]),
execute: { args in
guard case .string(let orderID)? = args["order_id"] else { return "order_id is missing" }
return await queryOrderByID(orderID)
})Writing it properly costs money, and you pay it again every turn: tool definitions are resent in full on every round. Using D2's figures, a solidly written tool runs about 100 to 150 tokens, so hanging 20 of them on the agent is a fixed overhead of two or three thousand per round, and a ten-round conversation burns twenty or thirty thousand on definitions alone. So only attach the tools the current scenario needs.
At this point the manual is solid. But no manual, however good, stops the next problem: the model generates arguments probabilistically, it is not a compiler. It will still write the order number as 12345 and the amount as a negative number. What does your tool do then?
Interview questions
What principles do you follow when designing tools for an agent โ how do you write the name, the description and the parameter schema?่ฎพ่ฎก Agent ็ๅทฅๅ ทๆถไฝ ไผ้ตๅพชๅชไบๅๅ๏ผๅๅญใๆ่ฟฐใๅๆฐๅๅซ่ฏฅๆไนๅ๏ผ
Common in ChinaCommon overseasBasic#tool-design#prompt-engineering๐ Unlock this chapter to see the answer keys.
When a tool call fails validation or errors out, how do you get the model to correct itself instead of failing the whole turn?ๅทฅๅ ท่ฐ็จๆฅ้ๆๅๆฐ้ๆณๆถ๏ผไฝ ๆไน่ฎฉๆจกๅ่ชๅทฑ็บ ๆญฃ่ไธๆฏ็ดๆฅๅคฑ่ดฅ๏ผ
Common in ChinaCommon overseasIntermediate#tool-calling#error-handling๐ Unlock this chapter to see the answer keys.
Which lifecycle events does an agent runtime typically expose, and why is waiting for the final return value not enough?Agent ็ไบไปถ็ณป็ปไธ่ฌไผๆด้ฒๅชไบ็ๅฝๅจๆไบไปถ๏ผไธบไปไนไธ่ฝๅช็ญๆ็ป่ฟๅๅผ๏ผ
Common in ChinaCommon overseasIntermediate#event-driven#observability๐ Unlock this chapter to see the answer keys.
How do you bound an agent's tool permissions, and is putting the rules in the system prompt enough?ๆไน้ๅฎๅทฅๅ ท็ๆ้่พน็๏ผ้ฟๅ Agent ่ถๆๆไฝ๏ผๆ่งๅๅ่ฟ็ณป็ปๆ็คบ่ฏๅคไธๅค๏ผ
Common in ChinaCommon overseasDeep dive#tool-permissions#security#prompt-injection๐ Unlock this chapter to see the answer keys.
