docs(agentforce): clarify pre_tool_call and post_tool_call authoring

apps/docs/docs/dialects/agentforce/patterns/ascript-patterns-action-chaining.md

@@ -100,6 +100,24 @@ reasoning:
       | Explain that the user is not eligible for this offer.
 ```
 
+## pre_tool_call and post_tool_call
+
+You may see `pre_tool_call` and `post_tool_call` in the generated Agent DSL schema or in compiled IR. Those names are **compiler/runtime concepts**, not Agent Script authoring keywords you write by hand in Agentforce.
+
+**What to write instead**
+
+- To run follow-up work after the LLM calls a reasoning action, use **chained actions** in `reasoning.actions` — nested `run`, `set`, `if` / `elif` / `else`, or `transition` under the tool (see examples above). The compiler emits that follow-up logic as `post_tool_call` for you.
+- Prefer the documented patterns on this page and in [Tools (Reasoning Actions)](../reference/ascript-ref-tools.md) over raw DSL hook fields.
+
+**Support status**
+
+| Hook             | Authoring support                                                                                                                                                                          |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `post_tool_call` | Supported **indirectly**: produced by the compiler from chained reasoning-action bodies (nested `run` / conditionals / transitions).                                                       |
+| `pre_tool_call`  | **Not supported** for Agent Script authoring today. It appears in generated schema types only; there is no documented authoring surface or compiler path that emits it. Do not rely on it. |
+
+If you need work to run before the LLM reasons, use `before_reasoning` / instructions at the start of the subagent — see [After Reasoning](../reference/ascript-ref-before-after-reasoning.md).
+
 ## Tips
 
 - **Use sequential instructions for deterministic flows**: When you always want actions to run in a specific order.
@@ -110,3 +128,4 @@ reasoning:
 - Reference: [Actions](../reference/ascript-ref-actions.md)
 - Reference: [Reasoning Instructions](../reference/ascript-ref-instructions.md)
 - Reference: [Tools (Reasoning Actions)](../reference/ascript-ref-tools.md)
+- Reference: [After Reasoning](../reference/ascript-ref-before-after-reasoning.md)

apps/docs/docs/dialects/agentforce/reference/ascript-ref-tools.md

@@ -116,9 +116,16 @@ reasoning:
             available when @variables.needs_expert_help == True
 ```
 
+## Chaining Follow-up Work After a Tool Call
+
+To run deterministic follow-up logic after the LLM calls a tool, nest `run`, `set`, conditionals, or `transition` under that tool in `reasoning.actions`. The compiler turns that nested body into `post_tool_call` behavior in the generated IR — you do not author `post_tool_call` (or `pre_tool_call`) directly.
+
+See [Action Chaining](../patterns/ascript-patterns-action-chaining.md#pre_tool_call-and-post_tool_call) for examples and support status.
+
 ## Related Topics
 
 - [Flow of Control](../ascript-flow.md)
 - [Actions](ascript-ref-actions.md)
 - [Utils](ascript-ref-utils.md)
 - [Variables](ascript-ref-variables.md)
+- Pattern: [Action Chaining](../patterns/ascript-patterns-action-chaining.md)