{
  "schemaVersion": 1,
  "id": "atlas-lesson-tool-contracts-schemas",
  "title": "Tool schemas and semantic validation",
  "category": "learning",
  "format": "Atlas lesson",
  "description": "Syntax, types, domain constraints, resource identity, output schema and result errors.",
  "canonicalUrl": "https://semiaifoundry.com/learn/atlas/tool-contracts-schemas/",
  "publishedDate": null,
  "revisionDate": "2026-10-07",
  "author": null,
  "topic": "From request to durable action",
  "series": null,
  "license": null,
  "rightsUrl": "https://semiaifoundry.com/ai-atlas/licenses.html",
  "version": "1.3.0",
  "status": "Published educational lesson",
  "evidenceScope": "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.",
  "contentCoverage": "published-lesson",
  "artifactUrl": "https://semiaifoundry.com/ai-atlas/lesson-data/tool-contracts-schemas-e27edc852f065160.json",
  "interactiveUrl": "https://semiaifoundry.com/ai-atlas/#tool-contracts-schemas",
  "related": [],
  "supersedes": [],
  "supersededBy": [],
  "contentHash": "6c67bde6960a45329e28d59f8f97cf93a939266c6f9c8166e4733ce8497fb51e",
  "contentLength": 6319,
  "jsonUrl": "https://semiaifoundry.com/agents/publications/atlas-lesson-tool-contracts-schemas.json",
  "markdownUrl": "https://semiaifoundry.com/agents/publications/atlas-lesson-tool-contracts-schemas.md",
  "sections": [
    {
      "id": "section-1",
      "title": "Tool schemas and semantic validation",
      "start": 47,
      "end": 447
    },
    {
      "id": "section-2",
      "title": "The mechanism",
      "start": 447,
      "end": 1733
    },
    {
      "id": "section-3",
      "title": "Science and assumptions",
      "start": 1733,
      "end": 1761
    },
    {
      "id": "section-4",
      "title": "Tool schemas and semantic validation · explicit relationship",
      "start": 1761,
      "end": 2854
    },
    {
      "id": "section-5",
      "title": "Engineering example",
      "start": 2854,
      "end": 3349
    },
    {
      "id": "section-6",
      "title": "Distinctions and tradeoffs",
      "start": 3349,
      "end": 3694
    },
    {
      "id": "section-7",
      "title": "Specifications and interfaces",
      "start": 3694,
      "end": 4250
    },
    {
      "id": "section-8",
      "title": "Interfaces",
      "start": 4250,
      "end": 4522
    },
    {
      "id": "section-9",
      "title": "Check your understanding",
      "start": 4522,
      "end": 4551
    },
    {
      "id": "section-10",
      "title": "A valid reservation call targets FAN-9, but the task asks for FAN-7. Which check catches the remaining problem?",
      "start": 4551,
      "end": 4918
    },
    {
      "id": "section-11",
      "title": "Evidence and scope",
      "start": 4918,
      "end": 5787
    },
    {
      "id": "section-12",
      "title": "Sources",
      "start": 5787,
      "end": 6088
    },
    {
      "id": "section-13",
      "title": "Continue exploring",
      "start": 6088,
      "end": 6111
    },
    {
      "id": "section-14",
      "title": "Foundations",
      "start": 6111,
      "end": 6212
    },
    {
      "id": "section-15",
      "title": "Related lessons",
      "start": 6212,
      "end": 6319
    }
  ],
  "citations": [
    {
      "title": "Explore in Atlas",
      "url": "https://semiaifoundry.com/ai-atlas/#tool-contracts-schemas"
    },
    {
      "title": "MCP tools",
      "url": "https://modelcontextprotocol.io/specification/2026-07-28/server/tools"
    },
    {
      "title": "Published lesson data",
      "url": "https://semiaifoundry.com/ai-atlas/lesson-data/tool-contracts-schemas-e27edc852f065160.json"
    },
    {
      "title": "Atlas releases and licensing",
      "url": "https://semiaifoundry.com/ai-atlas/licenses.html"
    },
    {
      "title": "Tools, memory & agent loop",
      "url": "https://semiaifoundry.com/learn/atlas/tool-loop/"
    },
    {
      "title": "Evaluation & the AGI frontier",
      "url": "https://semiaifoundry.com/learn/atlas/evaluation/"
    }
  ],
  "recordHash": "f47f3be9bccc631c2fee72dd0173c83901ec70e0460d2e5efd0f9dbd63ba9d43",
  "contentFormat": "text/markdown",
  "content": "From request to durable action · Atlas v1.3.0\n\n# Tool schemas and semantic validation\n\nSyntax, types, domain constraints, resource identity, output schema and result errors.\n\n[Explore in Atlas](https://semiaifoundry.com/ai-atlas/#tool-contracts-schemas)Logical state, task evidence and declared units; no physical assembly scale\n\nLearning objectiveLocate whether a failed call violates syntax, type, domain state, authority or the intended task.\n\n## The mechanism\n\nA 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.\n\n1.  The tool envelope selects a known operation and exactly the fields permitted by its input contract.\n2.  Type and range checks reject malformed values before authority checks or service.\n3.  Domain checks bind identifiers, evidence and current stock when the service executes.\n4.  The returned result has an explicit success or error meaning, while the final task checker remains independent.\n\n## Science and assumptions\n\n### Tool schemas and semantic validation · explicit relationship\n\n$$\nV_{\\mathrm{call}}=V_{\\mathrm{schema}}\\land V_{\\mathrm{domain}}\n$$\n\nA valid call in this example must satisfy both its input schema and current domain constraints.\n\nSymbols and units\n\nVcall\n\nValidity of this call before authorization and task evaluation\n\nBoolean\n\nVschema\n\nRequired fields, types and ranges match\n\nBoolean\n\nVdomain\n\nResource, evidence and stock constraints match\n\nBoolean\n\nThe 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.\n\nAssumptions This conjunction defines the lesson’s validation boundary. Authorization, exact approval and final task correctness are additional distinct predicates.\n\n## Engineering example\n\nThe 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.\n\n## Distinctions and tradeoffs\n\nWell-formed JSON does not establish that an action is authorized or correct.\n\nStricter contracts catch mistakes early but must evolve compatibly; overly broad free-form tools push more ambiguity into runtime checks.\n\nModel-generated arguments become inspectable operations only when their contracts are explicit.\n\n## Specifications and interfaces\n\nMechanism boundary\n\nWhat can a valid JSON object still get wrong?\n\nThis conjunction defines the lesson’s validation boundary. Authorization, exact approval and final task correctness are additional distinct predicates.\n\nEvidence type\n\nAuthored worked example\n\nThe 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.\n\n### Interfaces\n\nDeclared input and state Input\n\nThe tool envelope selects a known operation and exactly the fields permitted by its input contract.\n\nChecked outcome Output\n\nLocate whether a failed call violates syntax, type, domain state, authority or the intended task.\n\n## Check your understanding\n\n### A valid reservation call targets FAN-9, but the task asks for FAN-7. Which check catches the remaining problem?\n\n1.  JSON parsing alone\n2.  The independent task-goal check\n3.  The existence of an output schema\n\nAnswer and reasoning\n\nThe independent task-goal check\n\nA schema can validate the request shape while the requested entity remains wrong for this task.\n\n## Evidence and scope\n\nThe 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.\n\nThe 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.\n\n## Sources\n\n-   [MCP tools](https://modelcontextprotocol.io/specification/2026-07-28/server/tools)\n\n[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)\n\n## Continue exploring\n\n### Foundations\n\n-   [Tools, memory & agent loop](https://semiaifoundry.com/learn/atlas/tool-loop/)\n\n### Related lessons\n\n-   [Evaluation & the AGI frontier](https://semiaifoundry.com/learn/atlas/evaluation/)"
}