docs: unified capability-visibility pattern across function tools, MCP tools, and handoffs #4618

The Agents SDK now has several useful mechanisms for controlling what an agent can see at runtime:

• "FunctionTool.is_enabled";
• "Handoff.is_enabled";
• MCP "tool_filter";
• tool guardrails / approvals for execution-time checks;
• handoff input filtering.

Individually these APIs make sense.

I think there is an opportunity to document a single production pattern for using them together when capability availability comes from the same runtime policy.

Production-shaped use case

Consider an agent application where the capabilities valid for a request depend on runtime context such as:

• authenticated actor/client;
• channel or source;
• application variant;
• tenant;
• workflow state;
• feature flags.

The same application may expose capabilities through several SDK mechanisms:

• local function tools;
• MCP tools;
• specialist-agent handoffs.

Ideally the model-visible capability surface is derived consistently from one application policy rather than implementing slightly different conditions independently for each mechanism.

There is also an important distinction between visibility and authorization.

For example:

• a tool may be hidden entirely because it is irrelevant or unavailable for this client;
• a tool may be visible, but execution of a particular call may still require resource-level authorization based on its arguments;
• a handoff may be valid only during one workflow phase;
• after a handoff, the new agent should resolve its own effective capability set from the same run context.

Suggested documentation pattern

It would be useful to have one example showing something roughly like:

RunContext
|
+-- capability policy
|
+-- FunctionTool.is_enabled
+-- Handoff.is_enabled
+-- MCP tool_filter
|
+-- invocation-time authorization / guardrails

The example could explicitly establish that:

1. disabled capabilities are removed before the model sees them;
2. function tools, MCP tools, and handoffs can derive visibility from the same runtime context;
3. visibility filtering is not itself a security boundary;
4. argument/resource-level authorization belongs at invocation time;
5. capability policy is re-evaluated after agent transitions when appropriate.

Optional observability improvement

A related debugging capability would be useful: being able to inspect the effective model-visible capability set for a model invocation.

For production incidents, one of the first questions is often:

«What tools and handoffs did this agent actually see at this point in the run?»

If this information is already available through tracing/hooks, highlighting the recommended approach in the same example may be enough.

Scope

I'm not proposing another authorization framework or tool registry.

The existing primitives appear sufficient.

The main request is a canonical example showing how they compose into one coherent capability-visibility pattern.

I'd be happy to contribute that example/docs PR if maintainers think the pattern belongs in the SDK documentation.