Formatos de entrada y ejemplos

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.

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.

You can place input examples in two complementary places:

• In the tool description text (overall usage examples).
• In each parameter's description inside 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.

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.

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.

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.

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.

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.

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.

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.

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.

Apply the lesson to a real design decision.

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.