MCP Tool Contracts and Content
A tool is safe to automate only when discovery, arguments, results, pagination, and transport metadata agree on one contract. Define tool inputs and outputs with JSON Schema 2020-12. Validate structured results without assuming they are JSON objects. Choose between text, image, audio, resource links, and embedded resources. Reject unsafe x-mcp-header definitions before a tool reaches the model. Encode parameter-header values and verify exact header-to-body parity. Traverse cursor pagination without interpreting cursor values. Bound and authorize completion/complete suggestions. Calling a Python function is easy. Calling a remote capability through an AI host is a contract problem. The server publishes a descriptor. The client turns that descriptor into model context and user interface. The model creates arguments. A gateway may route the request from mirrored headers. The server executes the tool. The client then decides whether the result is safe and valid enough to return to the model. One weak boundary corrupts the whole chain. Consider five failures: The descriptor says the result is an object, but the server returns an array. The client stops pagination when nextCursor is an empty string. A token parameter is mirrored into an HTTP header and becomes visible to intermediaries. A Unicode routing value is sent as a raw header, then the gateway and origin interpret different bytes. A completion endpoint suggests a production environment to…
MCP Tool Contracts and Content: A tool is safe to automate only when discovery, arguments, results, pagination, and transport metadata agree on one contract.
This free lesson is part of the AI Engineering from Scratch curriculum. Read the full explanation, run the lesson code, and verify the result in the interactive reader or from the repository source.
Browse the complete course catalog or open this lesson on GitHub.