Toolang Grammar

Reference for .too source syntax. The Tree-sitter grammar in tree-sitter-toolang is the source of truth; this page summarizes the authored language shape for readers and examples.

Lexical structure

newline ::= "\n" | "\r\n"
blank_line ::= newline
line_text ::= /[^\r\n]*/
inline_text ::= /[^#\r\n]+/
raw_text ::= /raw block or fence content/
 
comment_line ::= "#" line_text newline
inline_comment ::= "#" line_text
line_end ::= inline_comment? newline
 
optional_marker ::= "?"
 
type_name ::= /[A-Z][A-Za-z0-9]*/
value_name ::= /[a-z][a-z0-9_-]*/

Toolang ignores spaces, tabs, and form feeds between grammar tokens. Newlines and block content remain structural.

Comments start with # and continue to the end of the line:

# Top-level comment
use skill openhat/workspace-search # Inline comment

Inside content blocks, comment-looking text is literal content unless the block position defines comments.

Program

program ::= (item | comment_line | blank_line)*
item ::= use | struct | psyche | skill | service | prompt | context | instruct | thunk

Names and types

type ::= base_type type_suffix*
base_type ::= builtin_type | user_type
builtin_type ::= "Text" | "Number" | "Boolean" | "Json" | "Message"
user_type ::= type_name
type_suffix ::= "[]"

Examples:

struct ReviewFinding:
  path: Text
  line?: Number
  tags: Text[]

Uses

Use declarations import reusable capabilities:

use ::= "use" cap_kind cap_ref line_end
cap_kind ::= "psyche" | "skill" | "service" | "prompt"
cap_ref ::= cap_uri | cap_shorthand
 
cap_uri ::= /[A-Za-z][A-Za-z0-9+.-]*:\/\/[^\s#]+/
cap_shorthand ::= /[A-Za-z0-9_@-][A-Za-z0-9_./:@-]*/

use psyche openhat/reviewer
use skill openhat/workspace-search
use service github://openhat-ai/caps/services/github@main
use prompt https://toolang.ai/rewrite

Structs

struct ::= "struct" struct_name ":" line_end struct_body
struct_name ::= type_name
struct_body ::= field+
field ::= field_name optional_marker? ":" type line_end
field_name ::= value_name

struct ReviewResult:
  summary: Text
  findings: ReviewFinding[]

Cap declarations

Capabilities may be declared inline in a .too file:

cap ::= psyche | skill | service | prompt
psyche ::= "psyche" cap_name ":" cap_body
skill ::= "skill" cap_name ":" cap_body
service ::= "service" cap_name ":" cap_body
prompt ::= "prompt" cap_name ":" cap_body
cap_name ::= value_name
 
cap_body ::= cap_indented | cap_markdown
cap_indented ::= line_end (property_eq | content_line | blank_line)*
cap_markdown ::= "```" "md"? line_end frontmatter? content_line* "```" newline
property_eq ::= property_key "=" property_value line_end
frontmatter ::= "---" newline (property_colon | frontmatter_comment)* "---" newline
property_colon ::= property_key ":" property_value line_end
frontmatter_comment ::= "#" line_text newline
property_key ::= value_name
property_value ::= inline_text

Indented body:

skill reviewer:
  description = Review source changes.
 
  Report concrete correctness issues.

Fenced Markdown body:

service github: ```md
---
transport: http
target: https://mcp.github.com/mcp
---
 
Use this service for GitHub operations.
```

Rules:

cap_shorthand must not start with . or /.
Indented cap properties use =.
Markdown fenced cap properties use frontmatter key: value lines.
+= and -= are thunk directive operators, not property operators.

Templates

Top-level context and instruct declarations define reusable text templates:

context ::= "context" context_name? ":" context_body
context_name ::= value_name
context_body ::= block_indented | block_fenced
 
instruct ::= "instruct" instruct_name? ":" instruct_body
instruct_name ::= value_name
instruct_body ::= block_indented | block_fenced
 
block_indented ::= line_end block_content?
block_fenced ::= "```" block_language? line_end block_content? "```" newline
block_content ::= raw_text
block_language ::= "md"

context workspace:
  Include current workspace state before the final user request.
 
instruct reviewer:
  Report only actionable review findings.

Defaults:

omitted context and instruct names default semantically to default

Rules:

context and instruct do not contain properties.
Bodies may be indented or fenced.
Runtime uses context templates to construct the context prompt prepended to the final user message.
Runtime uses instruct templates to construct model instructions.

Thunks

Thunks are executable units:

thunk ::= "thunk" thunk_name? params? output_type? ":" line_end thunk_body
thunk_name ::= value_name
params ::= "(" (param ("," param)*)? ")"
param ::= param_name optional_marker? ":" type
param_name ::= value_name
output_type ::= "->" type
 
thunk_body ::= directive* template_block_section? message_block*
directive ::= directive_key directive_op directive_csv line_end
directive_key ::= "models" | "tools" | "skills" | "services" | "psyches" | "hands" | "handoffs" | "recall"
directive_op ::= "=" | "+=" | "-="
directive_csv ::= bare_value ("," bare_value)*
bare_value ::= /[A-Za-z0-9_./:@-]+/
 
template_block_section ::= context_block instruct_block? | instruct_block context_block?
context_block ::= "context" ":" block_value
instruct_block ::= "instruct" ":" block_value
message_block ::= message_block_kind ":" block_value
message_block_kind ::= "user" | "assistant" | "tool"
block_value ::= block_inline | block_indented | block_fenced
block_inline ::= (block_name | block_content_inline) line_end
block_name ::= "default" | "none" | value_name
block_content_inline ::= inline_text

thunk review(input: Message, path: Text, focus?: Text) -> ReviewResult:
  models = gpt-5
  skills += code-review
  services += github
  tools = shell, filesystem
  hands += summarize
  recall = history, memory
 
  instruct: reviewer
  context: workspace
  user:
    Review {{path}} carefully.
    {{focus}}

Defaults:

omitted thunk name defaults semantically to default
omitted parameters imply (input: Message)
empty parentheses mean no parameters
omitted output type implies Message

Rules:

parameters require explicit types
input is reserved and must be first when declared
parentheses mean exact parameters; no implicit input is added
models and recall support only =
runtime validation checks referenced models, caps, tools, hands, and handoffs
hands declares sub-thunks this thunk may call
handoffs declares thunks this thunk may transfer control to
recall controls which retrieved message sources are prepended before thunk-local messages
thunk bodies contain directives, optional template blocks, and message blocks, not bare prompt text
one thunk may have at most one thunk-local context and at most one thunk-local instruct
a thunk may contain zero or more user, assistant, and tool message blocks, in declaration order
context and instruct values may be none, default, a named top-level template reference, inline text, an indented block, or a fenced block

Model call assembly

The runtime assembles a thunk call into tools, instructions, and messages for the model adapter.

tools is derived from available tool declarations and thunk capability directives.
instructions is generated from the selected instruct template.
messages starts with retrieved history according to recall, then appends thunk-local user, assistant, and tool blocks.
the final user message is formed by prepending a rendered context prompt to the user input.
recall = none disables history retrieval.
recall = default delegates to runtime policy.
recall = history, recall = memory, and recall = history, memory select explicit retrieval sources.