Tool Creation · Deep Dive
When an LLM calls a tool, it does so blindly. All it has is your schema — the name, description, and parameter definitions. If that schema is vague, the LLM will guess, and guesses produce bad tool calls.
A well-designed tool schema is a contract between the developer and the LLM. It tells the model exactly when to reach for this tool, what arguments to supply, and what the response will look like.
Use verb_noun names: search_jobs, send_email, create_invoice. Avoid vague names like do_stuff, process, or handle_input. Be consistent across your tool suite — if you use underscores, use them everywhere.
Every description should answer three questions: When should I call this? What arguments do I need? What will I get back? Include concrete format guidance for non-obvious parameters.
Use enum types for fixed values — this is the most reliable way to constrain output. Only mark a parameter required if the tool genuinely cannot function without it. Provide sensible defaults for optional parameters.
Concrete Example
def validate_tool_schema(schema):
warnings = []
name = schema.get("name", "")
if not name:
warnings.append("Tool has no name.")
elif name.lower() in ("process", "execute", "do_stuff"):
warnings.append(f"Name '{name}' is too vague.")
desc = schema.get("description", "")
if not desc or len(desc) < 20:
warnings.append("Description is too short or missing.")
for pname, pinfo in schema.get("parameters", {}).get("properties", {}).items():
if pname in ("input", "args", "data"):
warnings.append(f"Parameter '{pname}' is too vague.")
if not pinfo.get("description"):
warnings.append(f"Parameter '{pname}' has no description.")
return warningsScans a tool definition for common problems: vague names, short descriptions, poorly named parameters. Use in CI to catch issues before they reach users.
Name tools as action-object pairs. Avoid vague names.
When to call, what args, what response.
Use enum, min/max, format constraints. Prefer flat over nested.
Only mark required when the tool cannot function without it.