docs: Document tool approval denial reason propagation#2520
Conversation
Document that parent agents now receive a note in the delegation response when a user redirects a delegated sub-agent's task mid-execution (e.g. by denying a tool call with a reason). This gives the parent full context about how the task evolved. Ref: PR #2500
|
|
The latest updates on your projects. Learn more about Vercel for GitHub.
2 Skipped Deployments
|
|
Documents how tool approval denial reasons propagate to agents, following the fix in #2500.
|
There was a problem hiding this comment.
Documentation is technically accurate and matches the #2500 implementation. Two suggestions below — one for precision, one for completeness.
| ### Denial reason propagation | ||
|
|
||
| When a user denies a tool request with a `reason`, the agent receives the denial reason as a clean, human-readable string. This allows the agent to understand why the request was denied and adapt its behavior — for example, trying a different approach based on the user's feedback. | ||
|
|
||
| This is especially useful for redirecting agents. If a user denies a request for "San Francisco weather" with the reason "I want Tokyo instead", the agent can immediately act on that feedback and fetch Tokyo weather without requiring a separate follow-up message. | ||
|
|
There was a problem hiding this comment.
This subsection covers the executing agent's experience (Bug 1 fix from #2500) but doesn't mention the delegation visibility fix (Bug 2) — parent agents also receive a note about denied tool calls during delegation. Consider adding a sentence like: "In delegation scenarios, the parent agent also receives a note summarizing any mid-execution redirects — see Sub Agent Relationships." This makes the tool-approvals doc self-contained for readers who don't navigate to agent-relationships.
Co-authored-by: pullfrog[bot] <226033991+pullfrog[bot]@users.noreply.github.com>
|
🔎💬 Inkeep AI search and chat service is syncing content for source 'Inkeep Agent Framework Docs' |
There was a problem hiding this comment.
PR Review Summary
(2) Total Issues | Risk: Low
🟡 Minor (1) 🟡
🟡 1) tool-approvals.mdx Code example doesn't demonstrate denial reason
Issue: The new "Denial reason propagation" subsection (lines 56-60) explains that denial reasons enable agents to adapt behavior, but the Vercel AI SDK code example on the same page (lines 146-161) shows denial without passing a reason field: addToolApprovalResponse({ id: part.approval.id, approved: false }). This creates a gap between the documented capability and the demonstrated usage.
Why: Developers following the code example won't see how to actually implement the redirection use case described in the new documentation. The example demonstrates the pattern but misses the key feature being documented.
Fix: Consider updating the existing "Deny" button example to include a reason parameter, demonstrating the full capability:
addToolApprovalResponse({
id: part.approval.id,
approved: false,
reason: 'User wants different parameters', // Enables agent redirection
});This makes the new documentation immediately actionable for developers following the example.
Refs:
- tool-approvals.mdx:146-161 — existing example without reason
💭 Consider (2) 💭
Inline Comments:
- 💭 Consider:
visual-builder/tools/tool-approvals.mdx:107Inconsistent "for example" formatting vs TypeScript SDK page - 💭 Consider:
typescript-sdk/agent-relationships.mdx:89Long bullet point breaks parallel list structure
🕐 Pending Recommendations (1)
- 🟡
tool-approvals.mdxpullfrog suggested adding a cross-reference to delegation visibility — the TypeScript SDK tool-approvals page could note that parent agents also receive redirect context during delegation (see Sub Agent Relationships)
💡 APPROVE WITH SUGGESTIONS
Summary: The documentation accurately reflects the #2500 implementation — denial reasons are cleanly propagated to agents, and parent agents gain visibility into delegation redirects. The main suggestion is to update the code example to demonstrate the denial reason capability alongside the documentation that explains it. The inline style suggestions are optional polish.
Discarded (2)
| Location | Issue | Reason Discarded |
|---|---|---|
agent-relationships.mdx:89 |
Missing comma after "e.g." | Too nitpicky (LOW confidence) and both styles exist in codebase |
visual-builder/tools/tool-approvals.mdx |
Could link to specific #denial-reason-propagation anchor | Already has adequate cross-reference in "Handling approvals in your client" section |
Reviewers (3)
| Reviewer | Returned | Main Findings | Consider | While You're Here | Inline Comments | Pending Recs | Discarded |
|---|---|---|---|---|---|---|---|
pr-review-product |
3 | 1 | 0 | 0 | 0 | 1 | 1 |
pr-review-consistency |
3 | 0 | 2 | 0 | 2 | 0 | 1 |
pr-review-docs |
1 | 0 | 0 | 0 | 0 | 0 | 0 |
| Total | 7 | 1 | 2 | 0 | 2 | 1 | 2 |
Note: pr-review-docs finding (bullet length) was merged with pr-review-consistency finding addressing the same issue.
| 3. The user approves or denies the request | ||
| 4. If approved, the tool executes and the agent continues | ||
| 5. If denied, the agent receives the denial and can respond accordingly | ||
| 5. If denied, the agent receives a human-readable denial reason string (or a default message if no reason was provided), allowing it to understand why the request was denied and adapt its behavior (for example, trying a different approach or asking a clarifying question) |
There was a problem hiding this comment.
💭 Consider: Inconsistent "for example" formatting
Issue: This line uses (for example, in parentheses, while the parallel TypeScript SDK page uses em-dash formatting — for example,. Both styles exist in the codebase, but the em-dash pattern is more common in the docs.
Why: Consistency in formatting between parallel documentation pages helps developers build familiarity with the documentation style.
Fix: Consider aligning with the TypeScript SDK pattern:
| 5. If denied, the agent receives a human-readable denial reason string (or a default message if no reason was provided), allowing it to understand why the request was denied and adapt its behavior (for example, trying a different approach or asking a clarifying question) | |
| 5. If denied, the agent receives a human-readable denial reason string (or a default message if no reason was provided), allowing it to understand why the request was denied and adapt its behavior — for example, trying a different approach or asking a clarifying question |
Refs:
- TypeScript SDK tool-approvals.mdx:58 — uses em-dash pattern
| - The target Sub Agent executes a specific task | ||
| - Results are returned to the source Sub Agent | ||
| - The source Sub Agent continues processing | ||
| - If a user redirects the task mid-delegation (e.g. by denying a tool call with a reason like "I want Tokyo instead"), the delegation response includes a note about the redirect so the parent Sub Agent has full context about how the task evolved |
There was a problem hiding this comment.
💭 Consider: Long bullet point breaks parallel structure
Issue: This bullet point (~50 words with nested parenthetical) is significantly longer than the other items in this list (6-10 words each). This breaks the scannable parallel structure of the delegation relationships list.
Why: The existing bullets follow a pattern of short, declarative statements that are easy to scan. This longer item may be skimmed over despite containing important information.
Fix: Consider splitting into a shorter bullet followed by a <Tip> or note that elaborates:
- User redirects mid-delegation are passed back to the source Sub Agent
<Tip>
When a user denies a tool call with a reason (e.g., "I want Tokyo instead"), the parent Sub Agent receives full context about how the delegated task evolved during execution.
</Tip>Alternatively, keep the current format if the inline explanation is preferred for discoverability — this is a style preference.
Refs:
- agent-relationships.mdx:85-88 — existing short bullet pattern
Summary
Documents the improved tool approval denial reason propagation behavior introduced in #2500.
Changes
Visual Builder Tool Approvals
TypeScript SDK Tool Approvals
Sub Agent Relationships
Related PR
Closes documentation gap from #2500
cc @anubra266