# Tool schemas and semantic validation Canonical: https://semiaifoundry.com/learn/atlas/tool-contracts-schemas/ Revision: 2026-10-07 Rights: https://semiaifoundry.com/ai-atlas/licenses.html From request to durable action · Atlas v1.3.0 # Tool schemas and semantic validation Syntax, types, domain constraints, resource identity, output schema and result errors. [Explore in Atlas](https://semiaifoundry.com/ai-atlas/#tool-contracts-schemas)Logical state, task evidence and declared units; no physical assembly scale Learning objectiveLocate whether a failed call violates syntax, type, domain state, authority or the intended task. ## The mechanism A tool contract defines a name, input fields and types, output structure and error behavior. It turns a proposed operation into something a runtime can inspect before execution. Schema validation is only the first boundary: valid identifiers may refer to the wrong resource, and a positive integer quantity may still conflict with available stock or supporting evidence. Semantic checks therefore compare the request with current domain state. Authority and human approval remain separate conditions, so adding an approval field to arbitrary JSON does not grant permission. The fixture reservation tool accepts a bounded integer quantity and rejects additional fields. Its actual implementation also checks the asset, stock and manual fact. Even a semantically valid action for FAN-9 can fail a task whose goal was FAN-7; no schema can replace that external goal check. 1. The tool envelope selects a known operation and exactly the fields permitted by its input contract. 2. Type and range checks reject malformed values before authority checks or service. 3. Domain checks bind identifiers, evidence and current stock when the service executes. 4. The returned result has an explicit success or error meaning, while the final task checker remains independent. ## Science and assumptions ### Tool schemas and semantic validation · explicit relationship $$ V_{\mathrm{call}}=V_{\mathrm{schema}}\land V_{\mathrm{domain}} $$ A valid call in this example must satisfy both its input schema and current domain constraints. Symbols and units Vcall Validity of this call before authorization and task evaluation Boolean Vschema Required fields, types and ranges match Boolean Vdomain Resource, evidence and stock constraints match Boolean The authored malformed call sends quantity as the string "2". The numeric contract rejects it and no reservation service starts. The bounded policy then issues a new call with integer 2, which passes schema validation and still needs authority and exact review. In the wrong-entity case, integer 1 and a FAN-9 manual can be valid and internally consistent, yet they do not satisfy the FAN-7 task. Repairing syntax therefore changes only one layer of the evidence chain. Assumptions This conjunction defines the lesson’s validation boundary. Authorization, exact approval and final task correctness are additional distinct predicates. ## Engineering example The authored malformed call sends quantity as the string "2". The numeric contract rejects it and no reservation service starts. The bounded policy then issues a new call with integer 2, which passes schema validation and still needs authority and exact review. In the wrong-entity case, integer 1 and a FAN-9 manual can be valid and internally consistent, yet they do not satisfy the FAN-7 task. Repairing syntax therefore changes only one layer of the evidence chain. ## Distinctions and tradeoffs Well-formed JSON does not establish that an action is authorized or correct. Stricter contracts catch mistakes early but must evolve compatibly; overly broad free-form tools push more ambiguity into runtime checks. Model-generated arguments become inspectable operations only when their contracts are explicit. ## Specifications and interfaces Mechanism boundary What can a valid JSON object still get wrong? This conjunction defines the lesson’s validation boundary. Authorization, exact approval and final task correctness are additional distinct predicates. Evidence type Authored worked example The durable incident experience executes typed fixture tools, authority checks, exact review, receipts and independent final-state checks. Its policies are authored code and its storage boundary is local; it is not a real model or production workflow platform. ### Interfaces Declared input and state Input The tool envelope selects a known operation and exactly the fields permitted by its input contract. Checked outcome Output Locate whether a failed call violates syntax, type, domain state, authority or the intended task. ## Check your understanding ### A valid reservation call targets FAN-9, but the task asks for FAN-7. Which check catches the remaining problem? 1. JSON parsing alone 2. The independent task-goal check 3. The existence of an output schema Answer and reasoning The independent task-goal check A schema can validate the request shape while the requested entity remains wrong for this task. ## Evidence and scope The durable incident experience executes typed fixture tools, authority checks, exact review, receipts and independent final-state checks. Its policies are authored code and its storage boundary is local; it is not a real model or production workflow platform. The quantities and fixtures are authored. Source scope is recorded in the automation learning review manifest; no source benchmark or private system behavior is claimed. This conjunction defines the lesson’s validation boundary. Authorization, exact approval and final task correctness are additional distinct predicates. The durable incident experience executes typed fixture tools, authority checks, exact review, receipts and independent final-state checks. Its policies are authored code and its storage boundary is local; it is not a real model or production workflow platform. ## Sources - [MCP tools](https://modelcontextprotocol.io/specification/2026-07-28/server/tools) [Published lesson data](https://semiaifoundry.com/ai-atlas/lesson-data/tool-contracts-schemas-e27edc852f065160.json) · [Atlas releases and licensing](https://semiaifoundry.com/ai-atlas/licenses.html) ## Continue exploring ### Foundations - [Tools, memory & agent loop](https://semiaifoundry.com/learn/atlas/tool-loop/) ### Related lessons - [Evaluation & the AGI frontier](https://semiaifoundry.com/learn/atlas/evaluation/)