Lucid-toolkit use-toon

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):

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

<when_to_use>

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

@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>

SearchAction

CreateAction

UpdateAction

AssessAction

DeleteAction

AnalyzeAction

<core_syntax> <scalars>

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

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

<simple_arrays>

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

Format:

key[count]: item1,item2,...

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

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

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

</required_metadata>

<common_types>

Action

SearchAction

CreateAction

UpdateAction

AssessAction

ItemList

Thing

CreativeWork

SoftwareSourceCode

<action_status> For Action types, use

actionStatus

PotentialActionStatus

ActiveActionStatus

CompletedActionStatus

FailedActionStatus

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

</action_status>

<nested_types> Use

@type

@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:

file

name

path

url

content

text

created

dateCreated

author

author

count

numberOfItems

items

itemListElement

error

error

<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:

@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:

@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:

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

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}

<quoting_rules> Quote strings when they would be ambiguous:

""

"true"

"123"

"a,b"

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>

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

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