majiayu000/use-toon

<objective> TOON with schema.org vocabulary provides a standard format for prompting and instructing agents. Use it to structure task delegation, specify expected outputs, and ensure consistent responses from subagents and builtin agents.

Key benefits:

• Clear task structure: schema.org Action types define what the agent should do
• Expected output format: Specify result type so agents return consistent data
• Token efficiency: 30-60% fewer tokens than JSON = more context for agent reasoning
• Semantic interoperability: Standard vocabulary eliminates ambiguity

</objective>

<quick_start> <syntax> Object: key: value

Nested: Indentation (2 spaces)

Simple array: items[3]: a,b,c

Tabular array (uniform objects):

toon
users[2,]{id,name}:
  1,Alice
  2,Bob

</syntax>

<when_to_use> | Use TOON | Use JSON | |----------|----------| | Agent task prompts | External API calls | | Subagent instructions | Parsing with JSON.parse() | | Expected response format | Human debugging | | Agent-to-agent data | Deeply nested structures | </when_to_use> </quick_start>

<agent_prompting> <task_delegation> Structure agent tasks as schema.org Actions:

toon
@type: SearchAction
@id: task-001
description: Find all error handling patterns in the codebase

object:
  @type: SoftwareSourceCode
  codeRepository: ./src

expectedResult:
  @type: ItemList
  description: Files with error handling patterns

The agent knows:

• What to do: SearchAction = find/search
• What to search: object defines the target
• What to return: expectedResult specifies format

</task_delegation>

<instruction_format> When instructing agents, include:

[Task description in natural language]

Input:
[TOON block with @type, @id, and structured data]

Return your result in TOON format using:
- @type: [expected type, e.g., ItemList, Report, SearchAction]
- @id: [task-id]-result
- Use tabular notation for lists

</instruction_format>

<common_task_types> | Task | schema.org Type | Use | |------|-----------------|-----| | Find/search | SearchAction | Code search, file discovery | | Create/generate | CreateAction | Generate code, create files | | Modify/update | UpdateAction | Edit files, refactor code | | Validate/review | AssessAction | Code review, validation | | Delete/remove | DeleteAction | Remove files, clean up | | Analyze | AnalyzeAction | Code analysis, metrics | </common_task_types> </agent_prompting>

<core_syntax> <scalars>

toon
name: Alice
age: 30
active: true
score: null

Types auto-detected: strings, numbers, booleans, null. </scalars>

<nesting>

toon
user:
  name: Alice
  address:
    city: Boston
    zip: 02101

Use 2-space indentation for nesting. </nesting>

<simple_arrays>

toon
tags[3]: red,green,blue
ids[4]: 1,2,3,4

Format: key[count]: item1,item2,... </simple_arrays>

<tabular_arrays> For arrays of uniform objects (most efficient):

toon
users[3,]{id,name,role}:
  1,Alice,admin
  2,Bob,user
  3,Carol,user

Format: key[rowCount,]{col1,col2,...}:

Each row provides values in column order, comma-separated. </tabular_arrays>

</core_syntax>

<schema_vocabulary> Use schema.org types and properties as shared vocabulary between agents.

<required_metadata> Every TOON object MUST include:

• @type: schema.org type (e.g., Person, SearchAction, ItemList)
• @id: Unique identifier for the object

toon
@type: Person
@id: user-123
name: Alice
email: alice@example.com

</required_metadata>

<common_types> | Type | Use Case | Key Properties | |------|----------|----------------| | Action | Task execution | agent, object, result, actionStatus | | SearchAction | Search/find operations | query, result | | CreateAction | Creation operations | result, targetCollection | | UpdateAction | Modifications | targetCollection, result | | AssessAction | Validation/review | result, actionStatus | | ItemList | Collections | itemListElement, numberOfItems | | Thing | Generic entity | name, description, identifier | | CreativeWork | Documents/code | author, dateCreated, text | | SoftwareSourceCode | Code snippets | programmingLanguage, codeRepository | </common_types>

<action_status> For Action types, use actionStatus property:

| Status | Meaning | |--------|---------| | PotentialActionStatus | Not yet started | | ActiveActionStatus | In progress | | CompletedActionStatus | Successfully finished | | FailedActionStatus | Failed with error |

toon
@type: SearchAction
@id: search-001
actionStatus: CompletedActionStatus
query: auth handlers
resultCount: 3

</action_status>

<nested_types> Use @type for nested objects too:

toon
@type: CreateAction
@id: create-file-001
actionStatus: CompletedActionStatus

result:
  @type: SoftwareSourceCode
  name: auth.ts
  programmingLanguage: TypeScript

agent:
  @type: SoftwareApplication
  name: CodeAgent

</nested_types>

<property_conventions> Prefer schema.org property names:

| Instead of | Use | schema.org property | |------------|-----|---------------------| | file | name | Thing.name | | path | url | Thing.url | | content | text | CreativeWork.text | | created | dateCreated | CreativeWork.dateCreated | | author | author | CreativeWork.author | | count | numberOfItems | ItemList.numberOfItems | | items | itemListElement | ItemList.itemListElement | | error | error | Action.error | </property_conventions> </schema_vocabulary>

<prompting_patterns> <structured_input> When asking an agent to process structured data, use schema.org types:

Process this item list:

@type: ItemList
@id: pending-review
numberOfItems: 3

itemListElement[3,]{@type,identifier,name,status}:
  Product,A1,Widget,pending
  Product,A2,Gadget,shipped
  Product,A3,Gizmo,pending

Return pending items as an ItemList in TOON format.

</structured_input>

<requesting_toon_output> Include format instruction with schema.org guidance:

Return your answer in TOON format:
- Use appropriate schema.org @type (Action, ItemList, etc.)
- Include @id for the result object
- Use schema.org property names (name, description, result)
- Use tabular notation for uniform lists
- Wrap in ```toon code block

</requesting_toon_output>

<agent_task_pattern> For agent task delegation, structure as Action:

toon
@type: SearchAction
@id: task-001
description: Find all authentication handlers

object:
  @type: SoftwareSourceCode
  codeRepository: ./src

expectedResult:
  @type: ItemList
  description: Files with auth handlers

</agent_task_pattern>

<agent_response_pattern> Agents return completed Actions:

toon
@type: SearchAction
@id: task-001
actionStatus: CompletedActionStatus

result:
  @type: ItemList
  @id: task-001-result
  numberOfItems: 3

  itemListElement[3,]{@type,name,url,description}:
    SoftwareSourceCode,handleLogin,src/auth.ts:42,Login handler
    SoftwareSourceCode,handleLogout,src/auth.ts:78,Logout handler
    SoftwareSourceCode,authGuard,src/middleware.ts:15,Auth middleware

</agent_response_pattern>

<extraction_pattern> Parse TOON from LLM response:

python
def extract_toon(response: str) -> str:
    if "```toon" in response:
        return response.split("```toon")[1].split("```")[0].strip()
    elif "```" in response:
        return response.split("```")[1].split("```")[0].strip()
    return response.strip()

</extraction_pattern> </prompting_patterns>

<api_reference> Using the toon-format Python library (pip install toon-format):

python
from toon_format import encode, decode, estimate_savings

# Python dict to TOON
toon_str = encode(data, options={})

# TOON to Python dict
data = decode(toon_str, options={})

# Check efficiency
stats = estimate_savings(data)
# Returns: {"json_tokens": N, "toon_tokens": M, "savings_percent": X}

<options> | Option | Default | Use | |--------|---------|-----| | delimiter | "," | Row separator: ",", "\t", "|" | | lengthMarker | "" | Prefix for lengths: "", "#" | | strict | False | Validation strictness | </options> </api_reference>

<quoting_rules> Quote strings when they would be ambiguous:

| Value | Requires Quotes | Reason | |----------|-----------------|-----------------------------| | "" | Yes | Empty string | | "true" | Yes | Boolean keyword as string | | "123" | Yes | Numeric string (not number) | | "a,b" | Yes | Contains delimiter |

Unquoted values are parsed as their natural type. </quoting_rules>

<success_criteria> TOON with schema.org is correctly applied when:

• Every object has @type (schema.org type) and @id
• Property names follow schema.org conventions
• Actions use appropriate actionStatus values
• Tabular notation used for uniform itemListElement arrays
• Code blocks tagged with toon language
• Data round-trips correctly: decode(encode(data)) == data

</success_criteria>

<examples> <example name="search_action">

toon
@type: SearchAction
@id: search-auth-001
actionStatus: CompletedActionStatus
query: authentication handlers

result:
  @type: ItemList
  @id: search-auth-001-result
  numberOfItems: 3

  itemListElement[3,]{@type,name,url,description}:
    SoftwareSourceCode,handleLogin,src/auth.ts:42,Login handler
    SoftwareSourceCode,handleLogout,src/auth.ts:78,Logout handler
    SoftwareSourceCode,authGuard,src/middleware.ts:15,Auth middleware

</example>

<example name="create_action">

toon
@type: CreateAction
@id: create-component-001
actionStatus: CompletedActionStatus
description: Create React component

result:
  @type: SoftwareSourceCode
  @id: button-component
  name: Button.tsx
  url: src/components/Button.tsx
  programmingLanguage: TypeScript
  dateCreated: 2025-01-15

</example>

<example name="assess_action">

toon
@type: AssessAction
@id: validate-005
actionStatus: CompletedActionStatus
description: Validate outcome specification

result:
  @type: Report
  @id: validate-005-report
  name: Validation Report
  reportStatus: NeedsAttention

  itemListElement[2,]{@type,name,description}:
    Warning,missing-desc,Description field is empty
    Info,add-examples,Consider adding examples

</example>

<example name="item_list">

toon
@type: ItemList
@id: pending-tasks
description: Tasks awaiting review
numberOfItems: 3

itemListElement[3,]{@type,identifier,name,status}:
  Action,task-001,Implement auth,PotentialActionStatus
  Action,task-002,Add tests,ActiveActionStatus
  Action,task-003,Update docs,PotentialActionStatus

</example> </examples>