afv-library/skills/agentforce-generate/references/optimization-pattern-3-reference-syntax.md

Optimization Pattern 3: Fix Variable and Action Reference Syntax

Detection Logic

Scan all reasoning.instructions blocks for two categories of issues:

1. Incorrect reference syntax

• Variables referenced directly as @variables.X instead of {!@variables.X} in natural language text
• Actions/tools mentioned by name without using {!@actions.X} syntax

2. Missing action references

• Scan all actions in reasoning.actions and their definitions in actions: section
• Identify what use case each action serves based on its name, description, inputs/outputs
• Check if reasoning.instructions mentions those use cases without explicit {!@actions.X} references
• Match phrases like "retrieve details", "get contact", "update status", "look up", "search for" to action names

How to Fix

1. Change @variables.X to {!@variables.X} in natural language instruction text
2. Add {!@actions.X} syntax when referencing actions by their use case in instructions

Example

Before:

subagent CustomerService:
    reasoning:
        instructions: ->
            | Address user as @variables.userName. Help customers by looking up their account information and answering their questions.
        actions:
            GetAccount: @actions.GetCustomerAccount
                with email = @variables.customerEmail
            AnswerQuestion: @actions.AnswerWithKnowledge
                with query = ...
    actions:
        GetCustomerAccount:
            description: "Retrieves customer account details"
            inputs:
                "email": string
            outputs:
                "accountInfo": object
        AnswerWithKnowledge:
            description: "Answers questions using knowledge base"
            inputs:
                "query": string

After:

subagent CustomerService:
    reasoning:
        instructions: ->
            | Address user as {!@variables.userName}. Help customers by looking up their account information with {!@actions.GetAccount} and answering their questions with {!@actions.AnswerQuestion}.
        actions:
            GetAccount: @actions.GetCustomerAccount
                with email = @variables.customerEmail
            AnswerQuestion: @actions.AnswerWithKnowledge
                with query = ...
    actions:
        GetCustomerAccount:
            description: "Retrieves customer account details"
            inputs:
                "email": string
            outputs:
                "accountInfo": object
        AnswerWithKnowledge:
            description: "Answers questions using knowledge base"
            inputs:
                "query": string

Key improvements:

• Fixed variable reference: @variables.userName → {!@variables.userName}
• Matched action use cases to instructions:
  • "looking up their account information" → GetCustomerAccount → added {!@actions.GetAccount}
  • "answering their questions" → AnswerWithKnowledge → added {!@actions.AnswerQuestion}
• Explicit action references improve the LLM's ability to select the correct action at runtime