Tool Schema Design

Tool calling works or fails largely on the schema, because the description is the prompt. The model chooses among tools using their names and descriptions, and ambiguity there produces wrong selections that look like model failure.

What makes a tool schema work:

Distinct, non-overlapping purposes. Two tools that could both plausibly apply will be confused. If search_orders and get_order_history overlap, merge them or make the distinction explicit in both descriptions.

Descriptions that say when to use it and when not to, in plain language, including preconditions.

Few, strongly-typed parameters with constrained values — enumerations rather than free text wherever possible, since an invalid enumeration is a schema error and an invalid free-text value is a runtime surprise.

Errors that guide correction. "Invalid date format, expected YYYY-MM-DD" lets the model retry successfully; "Bad request" produces a loop.

The engineering constraints that surround it: validate every argument — tool arguments are model-generated and must be treated as untrusted input, which makes injection through tool parameters a real class of vulnerability; scope permissions to the user's own authority, never the application's; make tools idempotent where possible, because retries happen; and keep the tool count manageable, since selection accuracy degrades as the list grows — beyond roughly twenty, hierarchical selection or retrieval over tool descriptions works better than one flat list.