Tool Schemas as Contracts: tool_use, tool_calls, and JSON Schema
Agent-Assisted Engineering Check
Prerequisites
Day 73 control loop; basic JSON and function signatures from the Python block.
Learning Objective
Describe how production model APIs declare tools (name, description, JSON Schema parameters), how tool_use / tool_calls blocks carry name plus arguments, and how MCP generalizes the same contract into host/client/server roles - while scoping what the bounded fixture does not implement.
Instructions
1. A tool schema is a contract: a unique name, a natural-language description, and a JSON Schema parameters object listing properties, types, required fields, and additionalProperties policy. The model can only propose calls it has been shown schemas for.
2. Anthropic-style: the model returns a tool_use content block {id, name, input}; the client executes and replies with a tool_result block. OpenAI-style: the model returns tool_calls[{id, function:{name, arguments(JSON string)}}]; the client replies with role:"tool" messages. Both separate the model's request from the tool's execution - the same seam our harness draws between next_action and _tool_call.
3. MCP in one paragraph: a host process embeds clients; each client keeps one connection to a server exposing tools, resources, and prompts over JSON-RPC 2.0, with capability negotiation at initialize time; transports are stdio or streamable HTTP.
4. Compliance boundary: projects.agent_learning hard-codes three tools with hand-rolled argument checks. It demonstrates dispatch and validation shape only - it has no JSON-RPC framing, no initialize handshake, no tool discovery, and no schema negotiation. Study it as the loop's shape, not as a protocol implementation.
5. Why schemas matter: they are the surface a validator enforces; a malformed call fails at the schema layer before the tool runs.
Practice & Prediction Log
Express the three project tools (list_notes, read_note, write_report) as Anthropic-style tool definitions with name, description, and an input_schema JSON Schema each.
read_note requires a filename string matching a basename (no path separators); write_report requires a content string of at most 4096 characters; list_notes takes no properties.
[
{"name": "list_notes", "description": "List available note files", "input_schema": {"type": "object", "properties": {}, "additionalProperties": false}},
{"name": "read_note", "description": "Read one note file by basename", "input_schema": {"type": "object", "properties": {"filename": {"type": "string", "pattern": "^[^/\\\\]+$"}}, "required": ["filename"], "additionalProperties": false}},
{"name": "write_report", "description": "Write the final report file", "input_schema": {"type": "object", "properties": {"content": {"type": "string", "maxLength": 4096}}, "required": ["content"], "additionalProperties": false}}
]
Produce valid tool definitions for all three tools and state at least two protocol features the toy harness lacks (JSON-RPC framing, capability negotiation, discovery, streaming).
Authoritative Source Resources & Provenance
Anthropic Tool Use (Function Calling) Implementation Guide
Relevant Section / Range: Tool Use Overview, Schema Definitions, and Stop Reasons
Verified Version & Date: Claude API Specification (Verified: 2026-10-30)
Detailed production reference for client-side tool definitions, tool_use content blocks, stop reason tool_use, and tool_result response formatting.
REST API concepts, JSON schema specification, and basic Python client programming.
Offline mock request/response cycles and tool payload schemas are provided in the repo.
Compared Candidate Sources & Selection Analysis (2)
Protobuf and REST function declaration schema; Anthropic documentation provides explicit structured message block mechanics (tool_use / tool_result).
Multi-step tool calling parameter definitions; Anthropic specification demonstrates clear separated content blocks essential for inspectable event traces.
OpenAI Function Calling and Structured Outputs Guide
Relevant Section / Range: Function Calling Architecture and Strict Outputs
Verified Version & Date: OpenAI API Reference (Verified: 2026-10-30)
Widely adopted specification establishing tool choice parameters, JSON schema function descriptions, tool_calls arrays, and role: "tool" responses.
JSON data structures, chat completion roles, and schema validation.
Standard schema dictionaries and simulated tool call responses are bundled in the repository.
Compared Candidate Sources & Selection Analysis (2)
Follows OpenAI-compatible schema convention; OpenAI documentation serves as the primary originating reference for tools and tool_calls schemas.
Local model runtime implementation of function calling; OpenAI docs document the standard schema contract and strict output validation.