Contract-first AI agents begin by defining the task’s valid inputs, allowed information, expected output, acceptance criteria and observed completion state. A schema can prove that a value has the right structure; source checks and appropriate human authorisation are still needed to determine whether the result is correct and permissible.
This guide uses an original fictional Willow Worksheet Release Desk. Twelve proposed learning resources pass through different structural, mathematical, teacher-approval and external publication gates. By computing every denominator and testing changed circumstances, readers can distinguish a fluent draft from verified work.
It is an unnumbered technical companion to eduKateSG’s completed How Super Intelligence Works curriculum, not a claim that existing systems have reached artificial superintelligence.
Contents and learning routes
1. A task contract describes proof of completion · 2. Begin with the legitimate human purpose · 3. Five parts make an operational contract · 4. A schema tests structure, not truth · 5. The fictional Willow Worksheet Release Desk · 6. An example typed worksheet card · 7. Required fields create the first gate · 8. Types and units preserve the meaning of numbers · 9. Schema checks and semantic checks are independent · 10. The twelve-proposal funnel · 11. Calculate structural acceptance · 12. Calculate the content-check rate · 13. Calculate approval and verified publication · 14. A quality funnel is not a model benchmark by itself · 15. The workflow needs a no-action state · 16. Approval belongs to the exact artifact version · 17. An invariant is a rule that must remain true · 18. A state machine gives the rules operational form · 19. The model is not an independent source of approval · 20. Tool schemas and tool authority are different · 21. The invented Cedar Notice Desk transfer case · 22. A changed rubric can invalidate an approval · 23. When structure passes but the answer is wrong · 24. A paper exercise for parents and students · 25. Frequently asked questions · 26. Sources and the advanced learning route
1. A task contract describes proof of completion
A task contract states what must be true before the job may be called finished. For a school worksheet, those conditions might include the correct level, current topic, specified marking rubric, checked answer key and approval by the authorised tutor before publication. A generated paragraph is an intermediate product, not automatically an accepted result.
The strongest contracts distinguish content from workflow status. The same answer key might be mathematically correct while its publication remains pending or forbidden. A helpful AI application makes that distinction visible rather than reporting ‘done’ for every draft.
2. Begin with the legitimate human purpose
Before designing a JSON object, ask who the output serves and why. A teacher wants an appropriate learning resource, not an arbitrary number of generated questions. A parent wants a valid explanation, not a fabricated guarantee of a child’s examination outcome.
State the audience, source curriculum and conditions for a passing answer. The user request should drive the tools selected and the authority available. A machine-readable object cannot replace the decision about what the output is supposed to accomplish.
3. Five parts make an operational contract
A useful contract records identity and purpose, input/source boundaries, required output types and units, checks for semantic correctness, and the approval and external-state rules governing completion. Different systems may implement these fields differently; the conceptual layers remain useful.
If a model provides a numeric score with no denominator, the output contract is ambiguous. If it provides the right score with a stale rubric, the source contract fails. If it posts before staff review, the authority contract fails. Naming the layer prevents every issue being misclassified as a mysterious AI failure.
4. A schema tests structure, not truth
JSON Schema Draft 2020-12 defines mechanisms for specifying types, required fields and structural constraints. Such constraints can reject malformed tool arguments or results before later software attempts to use them.
A field called score can contain a number and still be wrong. A record can include a valid date that belongs to an earlier examination year. Schema validation answers whether a representation meets declared structural rules, not whether every claim is justified by a relevant source.
5. The fictional Willow Worksheet Release Desk
Willow is an invented learning centre handling twelve proposed worksheets in a paper-only teaching exercise. Each proposal needs a worksheet ID, academic level, topic, rubric version, answer-key reference, reviewer decision and publication status. The AI may prepare drafts but lacks authority to approve or publish them independently.
The packet later supplies how many proposals pass each stage. These figures are hypothetical examples rather than measurements of any real teacher, pupil, model or WordPress site. The purpose is to learn what evidence is needed before announcing that a resource was released.
6. An example typed worksheet card
One fictional card reads: worksheet_id W-07; level Secondary 2; topic linear equations; rubric_version R3; answer_key_reference AK-07; draft_status prepared; reviewer_status pending; publish_status not_attempted. These are application-specific teaching fields, not universal field names from an AI protocol.
Each field has an authority source. The assigned curriculum and answer key belong to the approved teaching materials. A human reviewer owns their decision. A publication service reports the actual saved record. A model must not invent an approval merely because the rest of the card looks complete.
7. Required fields create the first gate
Suppose a model returns the right topic and well-written questions but omits the rubric version. The record fails a required-field rule. The system should reject it for correction, not accept it because the model insists the work is ready.
If no approved rubric version is available, the right response is to report that the source is missing. Filling R3 from a previous worksheet would be an unsupported guess. Missing data and incorrect data require different repairs.
8. Types and units preserve the meaning of numbers
Consider a field containing 0.8. It might mean eighty percent, a probability, 0.8 marks or another measurement. The contract needs enough information to avoid silent reinterpretation. For example, correct_answers=8 and total_questions=10 support a calculated fraction of 8/10=0.8.
Do not convert an ambiguous bare number into a grade or a claim about pupil understanding. The schema can enforce representation; the semantic check must still confirm the source, denominator and meaning.
9. Schema checks and semantic checks are independent
A resource can pass the field-type check and fail because one algebra solution is wrong. A mathematically correct solution can fail routing because the worksheet ID is absent. Neither problem is cured by praising the model’s writing style.
The appropriate sequence is to check basic structure early, then inspect substantive content with independent methods. For mathematical material, a separate calculation and a qualified tutor’s review may be necessary. Each result remains attached to its own acceptance criterion.
10. The twelve-proposal funnel
Our invented Willow week begins with twelve AI-prepared worksheet candidates. Eight pass structural schema validation. Six of those eight pass content and evidence review. Five of those six receive explicit teacher approval. Four of the five approved records are confirmed published by the reporting cutoff.
The remaining items are not all equivalent failures. Some need a missing identifier, some require answer-key correction, some await authorisation and one approved record has no verified publication result yet. Status granularity makes the next step clear.
11. Calculate structural acceptance
Eight of twelve pass the first gate: 8/12=2/3, approximately 66.7%. Four need structural repair. That number says nothing about the mathematical correctness of all eight. It merely reflects compliance with the format and required-field rules.
A quality dashboard should include the numerator and denominator, and classify missing IDs or wrong field types separately from unsupported mathematics. Such precision helps engineers fix the right layer.
12. Calculate the content-check rate
Six of the eight schema-valid proposals pass the independent content check. The conditional content-pass rate is 6/8=75%. Relative to the original twelve candidates, the cumulative content-pass share is 6/12=50%.
Saying ‘75% of all generated worksheets were correct’ would therefore be a denominator error. Both measures are useful when labelled precisely, but they are not interchangeable.
13. Calculate approval and verified publication
Five of the six content-checked resources receive tutor approval, a conditional approval share of 5/6, approximately 83.3%. Four of the five approved resources reach independently verified publication, so the final-stage share is 4/5=80%.
From the original twelve proposals, four verified publications give 4/12=33.3%. That does not mean the other eight are worthless. It establishes that they did not reach the defined end state within the invented reporting period.
14. A quality funnel is not a model benchmark by itself
This packet is an operational example. It does not estimate future model error on unseen topics or compare two commercial systems. A real evaluation would need a representative task collection, stable acceptance rubric and independently assessed references.
Some drafts might later be corrected and published. Some may have been held because the timetable changed. Reporting a funnel without status and reasons can create misleading claims about model competence.
15. The workflow needs a no-action state
A publishing operation might be not_attempted, attempted, accepted_by_server, saved_as_draft, published or verified by readback. The application should use the states supported by its actual software and preserve what each one establishes.
If a tool returns a draft ID, the model may say the draft was saved. It must not claim public publication. If a response times out, the result may be uncertain; check the external record before retrying a consequential write.
16. Approval belongs to the exact artifact version
Suppose the teacher approved W-07 under rubric R3. If the AI edits two questions after that approval, the decision does not automatically cover the changed version. A stable revision identifier can bind the approval to the exact content that was examined.
Similarly, if a curriculum rubric changes, the application must establish which version applies. Reusing an old approval without its context can convert a legitimate review into a misleading permission for a different task.
17. An invariant is a rule that must remain true
An invariant for this invented service might say that every verified public worksheet has a checked answer key, an approved current rubric and a matching teacher decision. Another rule might prohibit private pupil information from appearing in public documents.
Build synthetic tests that try to move a draft into published status without the necessary evidence. The system should reject the forbidden transition regardless of whether the model confidently recommends it.
18. A state machine gives the rules operational form
A permitted route might be draft → schema_checked → content_checked → approved → publish_attempted → verified. Failed and cancelled states may return to the appropriate correction stage. Different software will use different names, but the transitions must reflect actual evidence and authority.
A state machine is stronger than a vague instruction to ‘be careful’ because the application can validate when the next action is allowed. It should not depend entirely on the model remembering what status it ought to have.
19. The model is not an independent source of approval
The assistant may write that a teacher approved an answer, but that statement alone does not establish the teacher’s actual decision. The application should obtain approval through the intended controlled process and record its identity and relevant content version.
The same principle applies to applications, reservations and official reports. An agent cannot grant itself the external authority that its task contract requires.
20. Tool schemas and tool authority are different
The MCP tools specification dated 28 July 2026 describes callable tools and schemas for interaction. The schema can support a precise request, but the target service must enforce the caller’s permissions.
A request can be well formed while attempting publication on the wrong site or without appropriate approval. Structural compliance is necessary for interoperability but insufficient to establish legitimate action.
21. The invented Cedar Notice Desk transfer case
A second fictional office prepares twenty public-notice drafts. Sixteen pass schema validation, twelve of those pass source checking, nine of those receive human approval and eight of those are confirmed published. All figures and organisations are invented for practice.
The conditional gate rates are 16/20=80%, 12/16=75%, 9/12=75% and 8/9≈88.9%. The final cumulative verified share is 8/20=40%. Readers must not reuse Willow’s 33.3% after the scenario changes.
22. A changed rubric can invalidate an approval
Now suppose the authorised notice policy changes after a draft was approved but before publication, introducing a compulsory field. The earlier decision may no longer cover the changed conditions. The record should be checked against the effective version, with appropriate renewed approval where required.
This does not imply every policy revision invalidates every past action. The task contract must define effective dates and which changes trigger review, rather than leaving the model to guess.
23. When structure passes but the answer is wrong
A fictional notice contains id N-14, date 12 November, room A and status prepared, each in valid types. The approved source N-14 actually lists room C. Structural validation passes; factual validation fails. The correction must come from the authorised source record rather than an invented room.
This demonstrates the central principle of contract-first AI: formatting is not factual grounding. The application should report the failed source-check gate and preserve the proposal’s original version for audit.
24. A paper exercise for parents and students
Give learners twelve fake worksheet cards with varying IDs, level labels, answers and approval statuses. First ask them to sort structural failures; then independently check the arithmetic; then identify which records genuinely have authorised approval and recorded publication.
Next change the answer key after one approval. A learner who recognises the need to recheck the affected artifact has transferred the concept beyond a memorised percentage.
25. Frequently asked questions
Does valid JSON prove a model’s answer is true? No. It proves only the chosen structural rules were satisfied. Does a task marked complete mean the user received the result? Not necessarily; delivery and external-state checks may remain.
Should a missing required field be guessed? No. Ask the appropriate source owner or preserve the unresolved state. Can an AI approve its own publication? Not merely because it is capable of generating text; authorisation belongs to the legitimate workflow.
Applied contract testing: versioned evidence, valid transitions and real outcomes
A correct output should be reproducible from the contract
The Willow packet provides a trace from the proposal to every acceptance gate. Another reviewer can reproduce eight structural passes, six content passes, five approvals and four confirmed publications without relying on the assistant’s own account of its reliability.
A contract needs enough information for that reproduction: record IDs, versioned source and rule, outcome status and when the check occurred. A vague status such as quality_good cannot support independent review when a parent questions what was released.
Distinguish input validation from result validation
Input validation protects the receiving tool from malformed or unauthorised requests. Result validation checks whether an operation returned a result of the expected structure and meaning. An input can be well formed while a remote tool returns an error, stale data or a partial outcome.
The two checks should not be merged. If a tool call fails, the correct state is not success simply because the request passed its schema. Equally, a correctly shaped result still needs appropriate source and permission verification.
An explicit null must have a defined meaning
A contract can allow a field to be null, but that should be deliberate. Does null mean not yet measured, not applicable, unavailable or redacted? Those states can lead to different next steps, especially when the consumer is trying to decide whether to proceed.
For example, an unknown reviewer decision is not equivalent to a rejected worksheet. A separate status field or a carefully defined enumeration can preserve the distinction. Allowing any arbitrary string increases the risk of interpretations diverging between the model and the application.
Reject incompatible units at the boundary
Imagine the fictional system reports a lesson duration of forty-five without specifying minutes, while the consumer expects seconds. A programmer may incorrectly interpret the same number as forty-five seconds. Making duration_minutes an explicit field, or pairing the value with a validated unit, prevents this ambiguity.
The numerical representation and educational claim must still be checked. If a source says a session is forty minutes, the schema cannot justify silently changing it to forty-five. Units protect interpretation, not the truth of the original number.
Check that source IDs belong to the same record
A model might provide worksheet_id W-07 but attach answer_key_reference AK-08. Both are valid strings, yet the key may belong to another resource. The semantic contract should check that the relationship between identifiers is supported by the approved source catalog.
This is a referential-integrity problem. It differs from a hallucinated algebra result, though both can make a worksheet unsafe to release. Type checking alone cannot guarantee the intended join is correct.
Keep teacher discretion separate from model scoring
A model can report that a worksheet passed all predetermined arithmetic checks while a teacher chooses not to publish it because the class has not studied a necessary prerequisite. That does not make the arithmetic tests wrong or the teacher’s review an unexplained defect.
The record should preserve a valid content-check status and a separate human decision with an appropriate reason. Conflating these statuses encourages the system to optimise for approvals instead of producing materials suitable for learners.
Acceptance gates should have error messages a person can use
A failure response saying invalid_output is often less helpful than a specific explanation such as missing rubric_version, unsupported algebra answer for question 4 or required approval absent. Different defects belong to different owners and should lead to different repairs.
For school material, correction should be educationally meaningful. A human teacher should not need to inspect several pages merely to discover which check failed. Clear gate-level feedback improves the workflow without pretending it guarantees pupil mastery.
A timeout creates an unknown external state
Suppose a publish request is accepted but the client connection closes before a response arrives. The tool may have committed the worksheet, saved it as a draft or performed no operation. A contract that allows only success and failure forces an unsupported choice.
Include a state such as outcome_uncertain, preserve the target identifier and inspect the actual publication record before retrying. This ties contract design to idempotency and recovery, which deserve separate technical treatment.
A revision can preserve one check while invalidating another
If a teacher corrects a spelling mistake after answer-key verification, mathematical correctness might remain valid while the exact approved artifact version changes. If the correction changes a question’s coefficient, both the answer key and approval need re-examination.
The application must have a policy identifying which checks are sensitive to which changes. Re-running every expensive test for every cosmetic edit can be wasteful; assuming that no check ever becomes stale can be unsafe. Version-aware dependencies provide a better route.
Schema versions are themselves part of the task
An application might accept output schema v1 with optional level, then introduce schema v2 requiring a specific academic level. A consumer validating under v2 may reject previously acceptable v1 records. That is a contract compatibility issue rather than proof the original material was factually incorrect.
Record the schema version used to produce and validate each artifact. Where migration is appropriate, transform records through a tested procedure rather than asking the language model to guess how old fields correspond to new obligations.
Strict formatting does not guarantee privacy
A schema can require a pupil_name field and thereby encourage unnecessary collection, even if the task only needs a public exercise. Contract design must consider data minimisation, not merely machine convenience. Sensitive fields and logs should be restricted by legitimate purpose and audience.
For Willow’s published materials, the public artifact can usually omit individual learner identity entirely. An internal administrative record may need different access controls. The output contract should make those products distinct.
Model output can be an untrusted input to another tool
An agent-generated JSON object may later drive a database operation. The receiving service must not assume the object is safe because a model produced it. Validate field types, allowed resource identifiers and caller permissions before allowing a consequential operation.
A lower-trust document may have influenced the model’s output. Prompt injection can therefore reach downstream systems through the generated arguments. Independent enforcement at the tool boundary remains important.
Tests should include negative cases, not only valid examples
A validation suite needs malformed inputs, wrong types, missing source IDs, stale rubrics, incorrect arithmetic, mismatched approvals and ambiguous external results. If every test is a clean successful worksheet, the system never demonstrates that it can stop an unsafe or unsupported publication.
The expected outcome for each case should be specified before running the model. A correct rejection can be a successful safety result, while an invented completion claim should fail even if its wording looks polished.
A small independent count for gate failures
Take a separate fictional set of ten worksheets: three are missing required fields, two have wrong answer keys, one lacks teacher approval and four have all necessary evidence and a verified publication. The four publishable outcomes represent 4/10=40% under this packet.
The categories in this example are mutually exclusive by stipulation. In real work, one resource may have multiple defects, so simply adding error counts can double-count rejected records. The data model should distinguish unique failed artifacts from the number of individual validation findings.
A review queue can become the bottleneck
Suppose the model drafts twenty valid worksheets during an hour, while the teacher can meaningfully review ten. The system accumulates ten unreviewed proposals under these simplified rates. Faster draft generation will not increase authorised publications unless some other stage changes.
The right performance report names draft throughput, content-check throughput, review completions and external publication separately. The model’s speed is only one part of the user-facing service.
A final changed-context contract test
Imagine that Willow is asked to release only material whose rubric_version is R4 and whose teacher approval was recorded after that rubric took effect. W-07’s old R3 decision no longer establishes compliance, even if the title, level and answer key are still valid strings.
A correct assistant identifies the changed condition, preserves already supported fields and requests an appropriate new check. It does not relabel the old approval or invent a current decision. That selective update is the transferable skill at the heart of contract-first AI.
The smallest useful audit card
For each accepted artifact, write one line containing the goal, ID, schema version, source version, numerical check, content-review result, approval identity, committed record identifier and readback observation. Leave genuinely unknown fields unresolved.
The card does not need to expose private pupil data or a model’s hidden reasoning. It needs the traceable evidence that a responsible reviewer can verify. A transparent small record is often more reliable than an impressive narrative of what an agent supposedly accomplished.
The complete proof-of-done rule
A finished Willow worksheet is not merely present in the model output. It has passed required structural and educational checks, carries the appropriate approval, appears at the intended external target and has been read back in the expected state. Every condition has a distinct owner and observable evidence.
A learner can transfer this rule to booking, research, publishing and public-service tasks: define what the person actually needs, identify what the model may help with and demand proof from the appropriate system before stating that the result is complete.
Continue from the acceptance contract: Agent Identity and Delegation enforces who may request the operation, Idempotency and Recovery handles repeated or uncertain writes, and Agent Observability records what genuinely happened. Together the chapters build from a valid draft toward a permitted, safely repeated and externally verified outcome. Explore the full 100-topic Super Intelligence curriculum and How X Works for related foundational mechanisms.
26. Sources and the advanced learning route
Official sources include JSON Schema Draft 2020-12, MCP tool schemas and the A2A task lifecycle. These describe structural and interaction mechanisms, not Willow’s invented outcomes.
Continue with eduKate’s MCP and A2A, Evaluations, Grounding and the 100-topic reading hub. No real pupil work, staff decision or publication was observed in these fictional laboratories. Sources reviewed 22 October 2026.