Vol. VII · Protocols & Tools · VII.1
Tools Are Structured Outputs
Factor 4: a tool call is JSON the model emitted. The 'tool' is your function. The ACI — names, descriptions, parameter schemas, error shapes — is the real prompt.
7 min read
humanlayer/12-factor-agentspydantic/pydantic-aimodelcontextprotocol/python-sdkopenai/openai-agents-pythonhuggingface/smolagents
Doctrine
- Name tools as verbs the model would say. Describe when to use them and when not to.
- Parameter schemas should be tight. Optional soup is how you get hallucinated kwargs.
- Return observations the model can use, not internal objects.
ACI, not API cosmetics
Anthropic: carefully craft the agent-computer interface; test it. Pydantic AI makes the schema the type system. MCP standardizes transport. smolagents uses Python as the schema. The common law: the model is a user of your CLI. Design it like a CLI you would give a new hire.
Anti-patterns
- One mega-tool with a JSON blob argument.
- Tool descriptions that duplicate the system prompt in 800 words.