Enjoyed this article? See more similar articles in 
Pega Gen AI Cookbook - Recipes series
Designing Efficient AI Contracts for Enterprise Agents
Using TOON to Define Input and Output Schemas
How should we define Input and Output schemas for AI agents?
More specifically:
Should schema definitions inside prompts be represented as JSON, or is there a better alternative?
Let’s explore why TOON can be an effective format for describing AI contracts while still allowing agents to return standard JSON responses.
Why Input and Output Schemas Matter
Every enterprise-grade AI agent operates using two critical contracts:
Input Contract
The input contract defines:
- What information is available to the agent
- Which fields are mandatory
- Data types and formats
- Relationships between data elements
Without a clearly defined input contract, the agent may incorrectly interpret the available information.
Output Contract
The output contract defines:
- What information the agent must return
- Required structure
- Formatting constraints
- Field definitions
- Validation rules
Without a consistent output contract, downstream applications may not be able to process responses reliably.
Real-World Example: Fraud Investigation Agent
Consider a fraud investigation agent responsible for:
- Detecting duplicate fraud reports
- Identifying conflict cases
- Recommending merges
- Summarizing fraud patterns
- Generating investigator actions
A common approach is to document the output contract inside the prompt using JSON.
Example:
{
“FraudPattern”: “One sentence”,
“OpenConflicts”: “Plain English”,
“DuplicateSummary”: “HTML”,
“HighestRisk”: “String”
}
This works.
However, it introduces an important question:
Is JSON the best format for describing the schema, or only the best format for delivering the response?
These are two very different problems.
Understanding the Difference Between Schema Definitions and Runtime Data
Many teams unintentionally mix these concepts.
Runtime Data
This is information that applications exchange.
Example:
{
“CustomerID”: “12345”,
“FraudType”: “Account Takeover”,
“FraudAmount”: 5000
}
JSON is the ideal format here because the data is being consumed by systems.
Schema Definition
This is instructional content.
Example:
{
“CustomerID”:“String”,
“FraudType”:“String”,
“FraudAmount”:“Number”
}
The model is not consuming this as actual data.
The model is consuming it as instructions.
This distinction is critical.
The Hidden Cost of JSON-Based Schema Definitions
When JSON is used to describe schemas inside prompts, additional structural overhead is introduced:
{
“FraudPattern”:“String”,
“HighestRisk”:“String”,
“DuplicateSummary”:“HTML”
}
Notice the repeated structural elements:
- Quotes
- Braces
- Commas
- Object nesting
- Property-name repetition
While these elements are necessary for machine-readable payloads, they provide little additional instructional value when simply documenting requirements.
The larger the schema becomes, the more structural overhead accumulates.
Input Schema Example: JSON vs TOON
JSON Input Schema Definition
{
“CustomerID”:“String”,
“FraudType”:“String”,
“FraudAmount”:“Number”,
“IncidentLocation”:“String”,
“IncidentDate”:“Date”
}
TOON Input Schema Definition
Input Schema
CustomerID = String
FraudType = String
FraudAmount = Number
IncidentLocation = String
IncidentDate = Date
Both representations communicate the same contract.
However, the TOON version removes all JSON syntax while preserving the information.
Output Schema Example: JSON vs TOON
JSON Output Schema
{
“DuplicateSummary”:“HTML”,
“FraudPattern”:“String”,
“HighestRisk”:“String”,
“OpenConflicts”:“String”
}
TOON Output Schema
Output Schema
DuplicateSummary = HTML
FraudPattern = String
HighestRisk = String
OpenConflicts = String
`
Again, the business meaning remains unchanged.
The TOON version simply focuses on readability and brevity.
Real Enterprise Example
Let’s examine a more realistic agent.
A Fraud Investigator Agent may require fields such as:
{
“DuplicateSummary”:“HTML”,
“MergeSummary”:“HTML”,
“FraudPattern”:“String”,
“NextSteps”:“HTML”,
“OpenConflicts”:“String”,
“DuplicateAlert”:{
“Count”:“Number”,
“Cases”:[]
},
“FraudIndicators”:{
“KeySignals”:“HTML”,
“FrequencySummary”:“String”,
“HighestRisk”:“String”
}
}
This structure is already growing significantly.
Now imagine:
- Detailed field descriptions
- Length constraints
- Validation rules
- Business requirements
- Formatting restrictions
The schema definition can quickly become larger than the actual business instructions.
TOON Equivalent
The same contract can be represented as:
Output Schema
DuplicateSummary - HTML
MergeSummary - HTML
FraudPattern - Single sentence
- Max 200 chars
NextSteps - HTML
- 3 to 5 actions
OpenConflicts - Plain text
- Max 300 chars
DuplicateAlert - Count = Number
- Cases
Case
- CaseId
- FiledDate
- Status
- Reason
FraudIndicators
- KeySignals
- FrequencySummary
- HighestRisk
The core requirements remain intact while the representation becomes easier to review.
Measuring the Difference
Using simplified versions of the Fraud Investigator schema:
Savings
| Format | Approx Chars | Reduction |
|---|---|---|
| JSON | 320 | - |
| TOON | 235 | ~27% |
| Savings | 85 | 25–30% smaller |
The exact numbers depend on:
- Field count
- Nesting depth
- Field descriptions
- Validation requirements
The larger and more complex the schema becomes, the greater the potential reduction.
Why the Reduction Matters
Every model operates within a finite context window.
That context window must contain:
- System instructions
- Input schema definitions
- Output schema definitions
- User requests
- Business data
- Generated responses
Reducing schema overhead creates more room for business information.
For example:
Instead of allocating thousands of characters to schema descriptions, those characters can be used for:
- Additional fraud cases
- Customer history
- Transaction history
- Investigation notes
- Supporting evidence
- Call transcripts
The result is more business context available to the model.
Benefits of TOON Schema Definitions
1. Reduced Prompt Size
This is the most measurable benefit.
TOON removes:
- Quotes
- Braces
- Nested JSON syntax
- Structural repetition
while preserving the same contract.
2. Easier Human Review
Architects and business analysts often review schema definitions.
This:
FraudPattern - Max 200 chars
is generally easier to consume than:
{
“FraudPattern”:“Maximum 200 characters”
}
especially when dealing with dozens of fields.
3. Better Maintainability
Business requirements change.
Updating:
FraudPattern - Max 300 chars is often simpler than modifying deeply nested JSON definitions.
4. More Context Available
Smaller schema definitions leave more space for:
- Business data
- Supporting documentation
- Historical records
- Case evidence
This can be particularly important for complex Agentic AI workflows.
JSON Still Matters
This article is not advocating replacing JSON.
JSON remains the preferred format for:
- REST APIs
- DX API
- Kafka events
- Data persistence
- Case property mapping
- System integrations
The optimization applies only to schema definitions inside prompts.
Key Takeaway
The goal is not to replace JSON.
The goal is to avoid using large JSON structures to describe other JSON structures inside prompts.
For enterprise AI solutions:
Use TOON to define input schemas.
Use TOON to define output schemas.
Continue using JSON for actual responses.
Continue using JSON for APIs and integrations.
A simple principle emerges:
Use TOON to describe the contract.
Use JSON to satisfy the contract.