@octavus/docs 0.0.5 → 0.0.7

package/content/04-protocol/04-tools.md

@@ -59,17 +59,17 @@ tools:
       query:
         type: string
         description: Search query
-      
+
       category:
         type: string
         description: Filter by category
         optional: true
-      
+
       maxPrice:
         type: number
         description: Maximum price filter
         optional: true
-      
+
       inStock:
         type: boolean
         description: Only show in-stock items
@@ -86,7 +86,7 @@ tools:
     description: Look up user account
     parameters:
       userId: { type: string }
-  
+
   create-support-ticket:
     description: Create a support ticket
     parameters:
@@ -136,17 +136,30 @@ handlers:
 
 ### In Prompts
 
-Reference tool results in prompts:
+Tool results are stored in variables. Reference the variable in prompts:
 
 ```markdown
 <!-- prompts/ticket-directive.md -->
 A support ticket has been created:
-- Ticket ID: {{TICKET.ticketId}}
-- Estimated Response: {{TICKET.estimatedResponse}}
+{{TICKET}}
+
+Let the user know their ticket has been created.
+```
+
+When the `TICKET` variable contains an object, it's automatically serialized as JSON in the prompt:
+
+```
+A support ticket has been created:
+{
+  "ticketId": "TKT-123ABC",
+  "estimatedResponse": "24 hours"
+}
 
 Let the user know their ticket has been created.
 ```
 
+> **Note**: Variables use `{{VARIABLE_NAME}}` syntax with `UPPERCASE_SNAKE_CASE`. Dot notation (like `{{TICKET.ticketId}}`) is not supported. Objects are automatically JSON-serialized.
+
 ### In Variables
 
 Store tool results for later use:
@@ -160,15 +173,13 @@ handlers:
       input:
         userId: USER_ID
       output: ACCOUNT  # Result stored here
-    
+
     Create ticket:
       type: tool-call
       tool: create-support-ticket
       input:
         summary: SUMMARY
         priority: medium
-        # Can reference ACCOUNT here
-        email: ACCOUNT.email
       output: TICKET
 ```
 
@@ -182,7 +193,7 @@ const session = client.agentSessions.attach(sessionId, {
     'get-user-account': async (args) => {
       const userId = args.userId as string;
       const user = await db.users.findById(userId);
-      
+
       return {
         name: user.name,
         email: user.email,
@@ -190,13 +201,13 @@ const session = client.agentSessions.attach(sessionId, {
         createdAt: user.createdAt.toISOString(),
       };
     },
-    
+
     'create-support-ticket': async (args) => {
       const ticket = await ticketService.create({
         summary: args.summary as string,
         priority: args.priority as string,
       });
-      
+
       return {
         ticketId: ticket.id,
         estimatedResponse: getEstimatedTime(args.priority),
@@ -218,7 +229,7 @@ tools:
       Retrieves the user's account information including name, email,
       subscription plan, and account creation date. Use this when the
       user asks about their account or you need to verify their identity.
-  
+
   # Avoid - vague
   get-data:
     description: Gets some data
@@ -234,4 +245,3 @@ tools:
         type: string
         description: Ticket priority level (low, medium, high, urgent)
 ```
-