docs: add guide for handling large tool outputs

[vinod151019]

Summary

Adds a new page at user-guide/concepts/tools/handling-large-outputs documenting three composable patterns for keeping multi-megabyte tool results out of the agent context window:

1. File Reference — write the payload to disk, return a path; a follow-up tool reads slices.
2. AfterToolCallEvent Hook — intercept results and truncate or summarize them uniformly; stash the full value in invocation_state for the caller.
3. Wrapper Tool — chain multiple steps inside a single tool so only the compact final result reaches the outer agent.

Closesstrands-agents/harness-sdk#2597.

Changes

• New page: src/content/docs/user-guide/concepts/tools/handling-large-outputs.mdx (137 lines, matches length and style of sibling pages like executors.mdx and vended-tools.mdx).
• Sidebar: one-line insertion in src/config/navigation.yml to list the page under Tools.

Verification

• npx astro build completes successfully; the new page builds at /docs/user-guide/concepts/tools/handling-large-outputs/.
• All internal links (../agents/hooks.md, ./custom-tools.md, ../plugins/index.md, etc.) resolve. Zero new broken links in broken-links.log.
• Every API call in the code examples verified against strands-agents/sdk-python main:
  • AfterToolCallEvent.result is writable (src/strands/hooks/events.py)
  • event.tool_use["toolUseId"] / ["name"] bracket syntax matches ToolUse TypedDict (src/strands/types/tools.py)
  • Agent(..., invocation_state=...) used instead of **kwargs (the latter is deprecating per src/strands/agent/agent.py)

Notes for reviewers

• The File-Reference example names run_query and read_file_slice as placeholders the reader supplies. I deliberately avoided shipping a shell-style executor snippet so readers don't copy-paste an unsafe subprocess.run(shell=True) into production.
• Placement under Tools rather than Agents: the page is primarily about tool-authoring patterns, though one of the three uses hooks.
• A companion working example is tracked at Add example: Handling large tool call results samples#244.

[vinod151019]

Hi @lizradway, thanks for the update on strands-agents/harness-sdk#2597.

Sharing what this PR adds for the team's review:

• New page: src/content/docs/user-guide/concepts/tools/handling-large-outputs.mdx (137 lines).
• Three patterns documented using today's primitives:
  • File reference — write payload to disk, return path.
  • AfterToolCallEvent hook — truncate result, stash full value in invocation_state.
  • Wrapper tool — chain steps inside one tool so only the final result reaches the outer agent.
• Sidebar: one-line insertion in src/config/navigation.yml under Tools.
• npx astro build passes. Zero new broken links.
• APIs verified against sdk-python main.

Related roadmap items for context:

• sdk-python#1296 (Large Tool Result Externalization via AfterToolCallEvent Hook)
• sdk-python#1678 (Large Content Aliasing, builds on #1296)

[strands-agent]

This repository has been merged into the strands-agents/harness-sdk monorepo and will be archived shortly. All new development happens there.

If this PR is still relevant, please recreate it against the monorepo. The code now lives under site/. Full commit history was preserved, so your base should be findable.

Apologies for the disruption, and thank you for contributing!

[vinod151019]

Summary

Adds a new page at user-guide/concepts/tools/handling-large-outputs documenting three composable patterns for keeping multi-megabyte tool results out of the agent context window:

1. File Reference — write the payload to disk, return a path; a follow-up tool reads slices.
2. AfterToolCallEvent Hook — intercept results and truncate or summarize them uniformly; stash the full value in invocation_state for the caller.
3. Wrapper Tool — chain multiple steps inside a single tool so only the compact final result reaches the outer agent.

Closesstrands-agents/harness-sdk#2597.

Changes

• New page: src/content/docs/user-guide/concepts/tools/handling-large-outputs.mdx (137 lines, matches length and style of sibling pages like executors.mdx and vended-tools.mdx).
• Sidebar: one-line insertion in src/config/navigation.yml to list the page under Tools.

Verification

• npx astro build completes successfully; the new page builds at /docs/user-guide/concepts/tools/handling-large-outputs/.
• All internal links (../agents/hooks.md, ./custom-tools.md, ../plugins/index.md, etc.) resolve. Zero new broken links in broken-links.log.
• Every API call in the code examples verified against strands-agents/sdk-python main:
  • AfterToolCallEvent.result is writable (src/strands/hooks/events.py)
  • event.tool_use["toolUseId"] / ["name"] bracket syntax matches ToolUse TypedDict (src/strands/types/tools.py)
  • Agent(..., invocation_state=...) used instead of **kwargs (the latter is deprecating per src/strands/agent/agent.py)

Notes for reviewers

• The File-Reference example names run_query and read_file_slice as placeholders the reader supplies. I deliberately avoided shipping a shell-style executor snippet so readers don't copy-paste an unsafe subprocess.run(shell=True) into production.
• Placement under Tools rather than Agents: the page is primarily about tool-authoring patterns, though one of the three uses hooks.
• A companion working example is tracked at Add example: Handling large tool call results samples#244.

[vinod151019]

Hi @lizradway, thanks for the update on strands-agents/harness-sdk#2597.

Sharing what this PR adds for the team's review:

• New page: src/content/docs/user-guide/concepts/tools/handling-large-outputs.mdx (137 lines).
• Three patterns documented using today's primitives:
  • File reference — write payload to disk, return path.
  • AfterToolCallEvent hook — truncate result, stash full value in invocation_state.
  • Wrapper tool — chain steps inside one tool so only the final result reaches the outer agent.
• Sidebar: one-line insertion in src/config/navigation.yml under Tools.
• npx astro build passes. Zero new broken links.
• APIs verified against sdk-python main.

Related roadmap items for context:

• sdk-python#1296 (Large Tool Result Externalization via AfterToolCallEvent Hook)
• sdk-python#1678 (Large Content Aliasing, builds on #1296)

[strands-agent]

This repository has been merged into the strands-agents/harness-sdk monorepo and will be archived shortly. All new development happens there.

If this PR is still relevant, please recreate it against the monorepo. The code now lives under site/. Full commit history was preserved, so your base should be findable.

Apologies for the disruption, and thank you for contributing!

[vinod151019]

Summary

Adds a new page at user-guide/concepts/tools/handling-large-outputs documenting three composable patterns for keeping multi-megabyte tool results out of the agent context window:

1. File Reference — write the payload to disk, return a path; a follow-up tool reads slices.
2. AfterToolCallEvent Hook — intercept results and truncate or summarize them uniformly; stash the full value in invocation_state for the caller.
3. Wrapper Tool — chain multiple steps inside a single tool so only the compact final result reaches the outer agent.

Closesstrands-agents/harness-sdk#2597.

Changes

• New page: src/content/docs/user-guide/concepts/tools/handling-large-outputs.mdx (137 lines, matches length and style of sibling pages like executors.mdx and vended-tools.mdx).
• Sidebar: one-line insertion in src/config/navigation.yml to list the page under Tools.

Verification

• npx astro build completes successfully; the new page builds at /docs/user-guide/concepts/tools/handling-large-outputs/.
• All internal links (../agents/hooks.md, ./custom-tools.md, ../plugins/index.md, etc.) resolve. Zero new broken links in broken-links.log.
• Every API call in the code examples verified against strands-agents/sdk-python main:
  • AfterToolCallEvent.result is writable (src/strands/hooks/events.py)
  • event.tool_use["toolUseId"] / ["name"] bracket syntax matches ToolUse TypedDict (src/strands/types/tools.py)
  • Agent(..., invocation_state=...) used instead of **kwargs (the latter is deprecating per src/strands/agent/agent.py)

Notes for reviewers

• The File-Reference example names run_query and read_file_slice as placeholders the reader supplies. I deliberately avoided shipping a shell-style executor snippet so readers don't copy-paste an unsafe subprocess.run(shell=True) into production.
• Placement under Tools rather than Agents: the page is primarily about tool-authoring patterns, though one of the three uses hooks.
• A companion working example is tracked at Add example: Handling large tool call results samples#244.

[vinod151019]

Hi @lizradway, thanks for the update on strands-agents/harness-sdk#2597.

Sharing what this PR adds for the team's review:

• New page: src/content/docs/user-guide/concepts/tools/handling-large-outputs.mdx (137 lines).
• Three patterns documented using today's primitives:
  • File reference — write payload to disk, return path.
  • AfterToolCallEvent hook — truncate result, stash full value in invocation_state.
  • Wrapper tool — chain steps inside one tool so only the final result reaches the outer agent.
• Sidebar: one-line insertion in src/config/navigation.yml under Tools.
• npx astro build passes. Zero new broken links.
• APIs verified against sdk-python main.

Related roadmap items for context:

• sdk-python#1296 (Large Tool Result Externalization via AfterToolCallEvent Hook)
• sdk-python#1678 (Large Content Aliasing, builds on #1296)

[strands-agent]

This repository has been merged into the strands-agents/harness-sdk monorepo and will be archived shortly. All new development happens there.

If this PR is still relevant, please recreate it against the monorepo. The code now lives under site/. Full commit history was preserved, so your base should be findable.

Apologies for the disruption, and thank you for contributing!

[vinod151019]

Summary

Adds a new page at user-guide/concepts/tools/handling-large-outputs documenting three composable patterns for keeping multi-megabyte tool results out of the agent context window:

1. File Reference — write the payload to disk, return a path; a follow-up tool reads slices.
2. AfterToolCallEvent Hook — intercept results and truncate or summarize them uniformly; stash the full value in invocation_state for the caller.
3. Wrapper Tool — chain multiple steps inside a single tool so only the compact final result reaches the outer agent.

Closesstrands-agents/harness-sdk#2597.

Changes

• New page: src/content/docs/user-guide/concepts/tools/handling-large-outputs.mdx (137 lines, matches length and style of sibling pages like executors.mdx and vended-tools.mdx).
• Sidebar: one-line insertion in src/config/navigation.yml to list the page under Tools.

Verification

• npx astro build completes successfully; the new page builds at /docs/user-guide/concepts/tools/handling-large-outputs/.
• All internal links (../agents/hooks.md, ./custom-tools.md, ../plugins/index.md, etc.) resolve. Zero new broken links in broken-links.log.
• Every API call in the code examples verified against strands-agents/sdk-python main:
  • AfterToolCallEvent.result is writable (src/strands/hooks/events.py)
  • event.tool_use["toolUseId"] / ["name"] bracket syntax matches ToolUse TypedDict (src/strands/types/tools.py)
  • Agent(..., invocation_state=...) used instead of **kwargs (the latter is deprecating per src/strands/agent/agent.py)

Notes for reviewers

• The File-Reference example names run_query and read_file_slice as placeholders the reader supplies. I deliberately avoided shipping a shell-style executor snippet so readers don't copy-paste an unsafe subprocess.run(shell=True) into production.
• Placement under Tools rather than Agents: the page is primarily about tool-authoring patterns, though one of the three uses hooks.
• A companion working example is tracked at Add example: Handling large tool call results samples#244.

[vinod151019]

Hi @lizradway, thanks for the update on strands-agents/harness-sdk#2597.

Sharing what this PR adds for the team's review:

• New page: src/content/docs/user-guide/concepts/tools/handling-large-outputs.mdx (137 lines).
• Three patterns documented using today's primitives:
  • File reference — write payload to disk, return path.
  • AfterToolCallEvent hook — truncate result, stash full value in invocation_state.
  • Wrapper tool — chain steps inside one tool so only the final result reaches the outer agent.
• Sidebar: one-line insertion in src/config/navigation.yml under Tools.
• npx astro build passes. Zero new broken links.
• APIs verified against sdk-python main.

Related roadmap items for context:

• sdk-python#1296 (Large Tool Result Externalization via AfterToolCallEvent Hook)
• sdk-python#1678 (Large Content Aliasing, builds on #1296)

[strands-agent]

This repository has been merged into the strands-agents/harness-sdk monorepo and will be archived shortly. All new development happens there.

If this PR is still relevant, please recreate it against the monorepo. The code now lives under site/. Full commit history was preserved, so your base should be findable.

Apologies for the disruption, and thank you for contributing!

[vinod151019]

Summary

Adds a new page at user-guide/concepts/tools/handling-large-outputs documenting three composable patterns for keeping multi-megabyte tool results out of the agent context window:

1. File Reference — write the payload to disk, return a path; a follow-up tool reads slices.
2. AfterToolCallEvent Hook — intercept results and truncate or summarize them uniformly; stash the full value in invocation_state for the caller.
3. Wrapper Tool — chain multiple steps inside a single tool so only the compact final result reaches the outer agent.

Closesstrands-agents/harness-sdk#2597.

Changes

• New page: src/content/docs/user-guide/concepts/tools/handling-large-outputs.mdx (137 lines, matches length and style of sibling pages like executors.mdx and vended-tools.mdx).
• Sidebar: one-line insertion in src/config/navigation.yml to list the page under Tools.

Verification

• npx astro build completes successfully; the new page builds at /docs/user-guide/concepts/tools/handling-large-outputs/.
• All internal links (../agents/hooks.md, ./custom-tools.md, ../plugins/index.md, etc.) resolve. Zero new broken links in broken-links.log.
• Every API call in the code examples verified against strands-agents/sdk-python main:
  • AfterToolCallEvent.result is writable (src/strands/hooks/events.py)
  • event.tool_use["toolUseId"] / ["name"] bracket syntax matches ToolUse TypedDict (src/strands/types/tools.py)
  • Agent(..., invocation_state=...) used instead of **kwargs (the latter is deprecating per src/strands/agent/agent.py)

Notes for reviewers

• The File-Reference example names run_query and read_file_slice as placeholders the reader supplies. I deliberately avoided shipping a shell-style executor snippet so readers don't copy-paste an unsafe subprocess.run(shell=True) into production.
• Placement under Tools rather than Agents: the page is primarily about tool-authoring patterns, though one of the three uses hooks.
• A companion working example is tracked at Add example: Handling large tool call results samples#244.

[vinod151019]

Hi @lizradway, thanks for the update on strands-agents/harness-sdk#2597.

Sharing what this PR adds for the team's review:

• New page: src/content/docs/user-guide/concepts/tools/handling-large-outputs.mdx (137 lines).
• Three patterns documented using today's primitives:
  • File reference — write payload to disk, return path.
  • AfterToolCallEvent hook — truncate result, stash full value in invocation_state.
  • Wrapper tool — chain steps inside one tool so only the final result reaches the outer agent.
• Sidebar: one-line insertion in src/config/navigation.yml under Tools.
• npx astro build passes. Zero new broken links.
• APIs verified against sdk-python main.

Related roadmap items for context:

• sdk-python#1296 (Large Tool Result Externalization via AfterToolCallEvent Hook)
• sdk-python#1678 (Large Content Aliasing, builds on #1296)

[strands-agent]

This repository has been merged into the strands-agents/harness-sdk monorepo and will be archived shortly. All new development happens there.

If this PR is still relevant, please recreate it against the monorepo. The code now lives under site/. Full commit history was preserved, so your base should be findable.

Apologies for the disruption, and thank you for contributing!

[vinod151019]

Summary

Adds a new page at user-guide/concepts/tools/handling-large-outputs documenting three composable patterns for keeping multi-megabyte tool results out of the agent context window:

1. File Reference — write the payload to disk, return a path; a follow-up tool reads slices.
2. AfterToolCallEvent Hook — intercept results and truncate or summarize them uniformly; stash the full value in invocation_state for the caller.
3. Wrapper Tool — chain multiple steps inside a single tool so only the compact final result reaches the outer agent.

Closesstrands-agents/harness-sdk#2597.

Changes

• New page: src/content/docs/user-guide/concepts/tools/handling-large-outputs.mdx (137 lines, matches length and style of sibling pages like executors.mdx and vended-tools.mdx).
• Sidebar: one-line insertion in src/config/navigation.yml to list the page under Tools.

Verification

• npx astro build completes successfully; the new page builds at /docs/user-guide/concepts/tools/handling-large-outputs/.
• All internal links (../agents/hooks.md, ./custom-tools.md, ../plugins/index.md, etc.) resolve. Zero new broken links in broken-links.log.
• Every API call in the code examples verified against strands-agents/sdk-python main:
  • AfterToolCallEvent.result is writable (src/strands/hooks/events.py)
  • event.tool_use["toolUseId"] / ["name"] bracket syntax matches ToolUse TypedDict (src/strands/types/tools.py)
  • Agent(..., invocation_state=...) used instead of **kwargs (the latter is deprecating per src/strands/agent/agent.py)

Notes for reviewers

• The File-Reference example names run_query and read_file_slice as placeholders the reader supplies. I deliberately avoided shipping a shell-style executor snippet so readers don't copy-paste an unsafe subprocess.run(shell=True) into production.
• Placement under Tools rather than Agents: the page is primarily about tool-authoring patterns, though one of the three uses hooks.
• A companion working example is tracked at Add example: Handling large tool call results samples#244.

[vinod151019]

Hi @lizradway, thanks for the update on strands-agents/harness-sdk#2597.

Sharing what this PR adds for the team's review:

• New page: src/content/docs/user-guide/concepts/tools/handling-large-outputs.mdx (137 lines).
• Three patterns documented using today's primitives:
  • File reference — write payload to disk, return path.
  • AfterToolCallEvent hook — truncate result, stash full value in invocation_state.
  • Wrapper tool — chain steps inside one tool so only the final result reaches the outer agent.
• Sidebar: one-line insertion in src/config/navigation.yml under Tools.
• npx astro build passes. Zero new broken links.
• APIs verified against sdk-python main.

Related roadmap items for context:

• sdk-python#1296 (Large Tool Result Externalization via AfterToolCallEvent Hook)
• sdk-python#1678 (Large Content Aliasing, builds on #1296)

[strands-agent]

This repository has been merged into the strands-agents/harness-sdk monorepo and will be archived shortly. All new development happens there.

If this PR is still relevant, please recreate it against the monorepo. The code now lives under site/. Full commit history was preserved, so your base should be findable.

Apologies for the disruption, and thank you for contributing!

[vinod151019]

Summary

Adds a new page at user-guide/concepts/tools/handling-large-outputs documenting three composable patterns for keeping multi-megabyte tool results out of the agent context window:

1. File Reference — write the payload to disk, return a path; a follow-up tool reads slices.
2. AfterToolCallEvent Hook — intercept results and truncate or summarize them uniformly; stash the full value in invocation_state for the caller.
3. Wrapper Tool — chain multiple steps inside a single tool so only the compact final result reaches the outer agent.

Closesstrands-agents/harness-sdk#2597.

Changes

• New page: src/content/docs/user-guide/concepts/tools/handling-large-outputs.mdx (137 lines, matches length and style of sibling pages like executors.mdx and vended-tools.mdx).
• Sidebar: one-line insertion in src/config/navigation.yml to list the page under Tools.

Verification

• npx astro build completes successfully; the new page builds at /docs/user-guide/concepts/tools/handling-large-outputs/.
• All internal links (../agents/hooks.md, ./custom-tools.md, ../plugins/index.md, etc.) resolve. Zero new broken links in broken-links.log.
• Every API call in the code examples verified against strands-agents/sdk-python main:
  • AfterToolCallEvent.result is writable (src/strands/hooks/events.py)
  • event.tool_use["toolUseId"] / ["name"] bracket syntax matches ToolUse TypedDict (src/strands/types/tools.py)
  • Agent(..., invocation_state=...) used instead of **kwargs (the latter is deprecating per src/strands/agent/agent.py)

Notes for reviewers

• The File-Reference example names run_query and read_file_slice as placeholders the reader supplies. I deliberately avoided shipping a shell-style executor snippet so readers don't copy-paste an unsafe subprocess.run(shell=True) into production.
• Placement under Tools rather than Agents: the page is primarily about tool-authoring patterns, though one of the three uses hooks.
• A companion working example is tracked at Add example: Handling large tool call results samples#244.

[vinod151019]

Hi @lizradway, thanks for the update on strands-agents/harness-sdk#2597.

Sharing what this PR adds for the team's review:

• New page: src/content/docs/user-guide/concepts/tools/handling-large-outputs.mdx (137 lines).
• Three patterns documented using today's primitives:
  • File reference — write payload to disk, return path.
  • AfterToolCallEvent hook — truncate result, stash full value in invocation_state.
  • Wrapper tool — chain steps inside one tool so only the final result reaches the outer agent.
• Sidebar: one-line insertion in src/config/navigation.yml under Tools.
• npx astro build passes. Zero new broken links.
• APIs verified against sdk-python main.

Related roadmap items for context:

• sdk-python#1296 (Large Tool Result Externalization via AfterToolCallEvent Hook)
• sdk-python#1678 (Large Content Aliasing, builds on #1296)

[strands-agent]

This repository has been merged into the strands-agents/harness-sdk monorepo and will be archived shortly. All new development happens there.

If this PR is still relevant, please recreate it against the monorepo. The code now lives under site/. Full commit history was preserved, so your base should be findable.

Apologies for the disruption, and thank you for contributing!

[vinod151019]

Summary

Adds a new page at user-guide/concepts/tools/handling-large-outputs documenting three composable patterns for keeping multi-megabyte tool results out of the agent context window:

1. File Reference — write the payload to disk, return a path; a follow-up tool reads slices.
2. AfterToolCallEvent Hook — intercept results and truncate or summarize them uniformly; stash the full value in invocation_state for the caller.
3. Wrapper Tool — chain multiple steps inside a single tool so only the compact final result reaches the outer agent.

Closesstrands-agents/harness-sdk#2597.

Changes

• New page: src/content/docs/user-guide/concepts/tools/handling-large-outputs.mdx (137 lines, matches length and style of sibling pages like executors.mdx and vended-tools.mdx).
• Sidebar: one-line insertion in src/config/navigation.yml to list the page under Tools.

Verification

• npx astro build completes successfully; the new page builds at /docs/user-guide/concepts/tools/handling-large-outputs/.
• All internal links (../agents/hooks.md, ./custom-tools.md, ../plugins/index.md, etc.) resolve. Zero new broken links in broken-links.log.
• Every API call in the code examples verified against strands-agents/sdk-python main:
  • AfterToolCallEvent.result is writable (src/strands/hooks/events.py)
  • event.tool_use["toolUseId"] / ["name"] bracket syntax matches ToolUse TypedDict (src/strands/types/tools.py)
  • Agent(..., invocation_state=...) used instead of **kwargs (the latter is deprecating per src/strands/agent/agent.py)

Notes for reviewers

• The File-Reference example names run_query and read_file_slice as placeholders the reader supplies. I deliberately avoided shipping a shell-style executor snippet so readers don't copy-paste an unsafe subprocess.run(shell=True) into production.
• Placement under Tools rather than Agents: the page is primarily about tool-authoring patterns, though one of the three uses hooks.
• A companion working example is tracked at Add example: Handling large tool call results samples#244.

[vinod151019]

Hi @lizradway, thanks for the update on strands-agents/harness-sdk#2597.

Sharing what this PR adds for the team's review:

• New page: src/content/docs/user-guide/concepts/tools/handling-large-outputs.mdx (137 lines).
• Three patterns documented using today's primitives:
  • File reference — write payload to disk, return path.
  • AfterToolCallEvent hook — truncate result, stash full value in invocation_state.
  • Wrapper tool — chain steps inside one tool so only the final result reaches the outer agent.
• Sidebar: one-line insertion in src/config/navigation.yml under Tools.
• npx astro build passes. Zero new broken links.
• APIs verified against sdk-python main.

Related roadmap items for context:

• sdk-python#1296 (Large Tool Result Externalization via AfterToolCallEvent Hook)
• sdk-python#1678 (Large Content Aliasing, builds on #1296)

[strands-agent]

This repository has been merged into the strands-agents/harness-sdk monorepo and will be archived shortly. All new development happens there.

If this PR is still relevant, please recreate it against the monorepo. The code now lives under site/. Full commit history was preserved, so your base should be findable.

Apologies for the disruption, and thank you for contributing!