输入格式与示例
展示具体的输入示例以消除歧义。
输入格式与示例 是 CoddyKit 上的免费 Claude Architect 课时。 这是第 4 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 Claude Architect 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Claude Architect 课程共包含 4 节课。
本课时的部分内容尚未翻译，以英文显示。
Why Input Formats Matter
A tool description is the primary mechanism Claude uses to decide when and how to call a tool. Names alone don't carry enough signal. A strong description covers purpose, return values, edge cases, applicability boundaries, and crucially the input formats.
This lesson focuses on one high-leverage technique: showing concrete input examples so the model never has to guess what a parameter should look like.
Ambiguity Is the Enemy
Imagine a tool with a parameter called date. Is it 2026-06-10? 06/10/2026? June 10? A Unix timestamp? Without an example, Claude has to infer the format, and inference under ambiguity is where malformed tool calls come from.
An ambiguous schema doesn't fail loudly. It fails quietly, by producing inputs your backend rejects. Concrete examples remove that ambiguity at the source.
Where Examples Live
You can place input examples in two complementary places:
- In the tool description text (overall usage examples).
- In each parameter's
descriptioninside the JSON Schema (per-field format).
Both feed the same selection-and-formatting engine. Put the format guidance closest to the field it governs, and add a holistic example for the whole call.
search_orders = {
"name": "search_orders",
"description": (
"Search a customer's orders by date range. "
"Dates use ISO 8601 (YYYY-MM-DD). "
"Example call: search_orders(start='2026-01-01', end='2026-03-31')."
),
"input_schema": {
"type": "object",
"properties": {
"start": {
"type": "string",
"description": "Inclusive start date, ISO 8601. Example: '2026-01-01'."
},
"end": {
"type": "string",
"description": "Inclusive end date, ISO 8601. Example: '2026-03-31'."
}
},
"required": ["start", "end"]
}
}A Weak Description vs a Strong One
Compare these. The weak version forces guessing; the strong one shows exactly what valid input looks like.
- Weak: "Look up a customer."
- Strong: purpose + input format + example + return values + edge cases.
Minimal, ambiguous descriptions are a classic anti-pattern that causes tool misrouting and malformed arguments.
# Weak: model must guess the id format
bad = {
"name": "get_customer",
"description": "Look up a customer."
}
# Strong: shows the exact format with an example
good = {
"name": "get_customer",
"description": (
"Fetch a verified customer profile by account ID. "
"account_id is the 8-char alphanumeric code from the "
"welcome email, e.g. 'A1B2C3D4' (not the email address). "
"Returns name, tier, and verified flag. "
"Returns isError if no match — ask for more identifiers, never guess."
)
}Show the Shape of Structured Inputs
When a parameter is an object or array, a single example is worth a paragraph of prose. Show the model the literal shape it should emit.
This is especially valuable for nested filters, list items, or any field where the structure isn't obvious from the type alone.
filter_param = {
"type": "object",
"description": (
"Structured filter. Example: "
'{"status": "shipped", "min_total": 50, '
'"tags": ["priority", "gift"]}. '
"Omit a key to leave that dimension unfiltered."
),
"properties": {
"status": {"type": "string", "enum": ["pending", "shipped", "delivered"]},
"min_total": {"type": "number"},
"tags": {"type": "array", "items": {"type": "string"}}
}
}Enums Beat Free Text for Fixed Sets
When a field has a known, finite set of valid values, encode them as an enum rather than describing them in prose. The schema then constrains the model directly.
For extensibility, add an "other" enum value plus a free-text detail field, so new cases don't force the model to invent an invalid value.
reason = {
"type": "object",
"properties": {
"category": {
"type": "string",
"enum": ["defective", "wrong_item", "late", "other"],
"description": "Refund reason. Use 'other' for anything unlisted."
},
"detail": {
"type": "string",
"description": "Free text. Required only when category is 'other'."
}
},
"required": ["category"]
}Examples Reduce Hallucinated Inputs
Few-shot examples are one of the most reliable prompting tools. With 2-4 targeted examples per ambiguity, the model generalizes the pattern rather than just repeating it.
Applied to tool inputs, examples are best for consistency, edge cases, output format, and reducing hallucination, exactly the failure modes that produce bad tool arguments.
phone = {
"type": "string",
"description": (
"Phone in E.164 format. "
"Examples: '+14155552671', '+442071838750'. "
"Do NOT include spaces, dashes, or parentheses."
)
}Mark Required Only What's Always Present
Examples tell the model what valid input looks like; the required array tells it what must appear. A critical rule: mark a field required only if it is always present.
If you require a field that may be absent from the source, the model will fabricate a value to satisfy the schema. Optional-but-well-exemplified beats required-but-sometimes-missing.
schema = {
"type": "object",
"properties": {
"order_id": {"type": "string", "description": "e.g. 'ORD-90412'"},
"coupon_code": {
"type": "string",
"description": "Optional. e.g. 'SAVE10'. Omit if none on the order."
}
},
# coupon_code is NOT required — it may be absent.
"required": ["order_id"]
}Call Out Edge Cases in the Example
Good descriptions state applicability boundaries: what the tool does, and what it does NOT handle. Bake those boundaries into your examples so the model recognizes when an input is out of scope.
This keeps overlapping tools from being misrouted, since the example clarifies which tool owns which input shape.
lookup_order = {
"name": "lookup_order",
"description": (
"Look up ONE order by its order ID. "
"order_id format: 'ORD-' + 5 digits, e.g. 'ORD-90412'. "
"Does NOT search by customer name or email — "
"use search_orders for that. "
"Returns isError (category='validation') if the ID is malformed."
)
}Pair Input Examples With Structured Errors
Even with great examples, some inputs will be invalid. The tool's error contract should be just as explicit, so the model can recover.
Return structured errors: an isError flag plus errorCategory (transient / validation / business / permission), isRetryable, a message, and the attempted_query. Generic "Operation failed" blocks recovery; structured errors enable intelligent routing and a corrected retry.
{
"isError": true,
"errorCategory": "validation",
"isRetryable": true,
"message": "start must be ISO 8601 (YYYY-MM-DD); got '06/10/2026'.",
"attempted_query": {"start": "06/10/2026", "end": "2026-03-31"},
"partial_results": null
}Examples + Retry-With-Feedback
When a tool input comes back malformed, use retry-with-feedback: send the original request, the wrong output, and the exact validation error back to the model. Format and structural errors are exactly what this fixes.
Note the limit: retry helps when the input was misformatted, not when the needed info is simply absent from the source. Examples prevent the first class of error; nothing invents missing facts.
messages.append({
"role": "user",
"content": (
"Your tool call failed validation. "
"start must match YYYY-MM-DD. "
"You sent '06/10/2026'. "
"Reissue the call with the corrected format."
)
})
# Resend full history; the model keeps no state between turns.Quick Check
Apply the lesson to a real design decision.
Recap: Make Inputs Unambiguous
Key takeaways:
- Tool descriptions drive selection and formatting, so invest in them, not just names.
- Show concrete input examples at the field level and a full-call example in the description.
- Use enums (with an 'other' + detail field) for fixed sets; show the literal shape of objects and arrays.
- Mark a field required only if it is always present, otherwise the model fabricates.
- Back examples with structured errors (errorCategory, isRetryable, attempted_query) so retry-with-feedback can correct format mistakes, though it cannot supply absent facts.
Concrete examples are the cheapest, highest-leverage way to stop malformed tool calls before they happen.
用 AI 导师学习 Python — 免费
在浏览器中编写并运行真实代码，获得全天候 AI 导师的即时帮助，并在网页或应用中继续学习。
- 课程
- 26
- 课程
- 104
常见问题解答
「输入格式与示例」课时是免费的吗？
是的 — 「输入格式与示例」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Claude Architect 课程的其余内容，请升级到 CoddyKit PRO。 Claude Architect 课程共包含 4 节课。
「输入格式与示例」这节课中我会学到什么？
展示具体的输入示例以消除歧义。 你通过在浏览器中直接运行的动手代码来练习 Claude Architect，全天候 AI 导师会在你学习这节课的过程中回答你的问题。
学习 Claude Architect 需要有经验吗？
无需任何先前经验。CoddyKit 上的 Claude Architect 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 4 节课，共 4 节。
「输入格式与示例」课时需要多长时间？
大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。
我能在这节 Claude Architect 课中编写并运行代码吗？
能。每节 Claude Architect 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。