Add examples field to ToolDefinition and send it to Anthropic

[AlanPonnachan]

Summary
This PR revives and improves upon the stale PR #3619 to add support for providing example inputs to tools. This feature allows developers to provide 1-5 realistic examples of tool usage, helping models (specifically Anthropic models) understand correct usage patterns, optional fields, and complex nested structures.

Key Changes

• Renaming: Renamed input_examples to examples across the codebase (per maintainer feedback), aligning with parameters_json_schema.
• Tool Support: Added examples field to ToolDefinition and Tool class.
• Output Tool Support: Added examples support to ToolOutput, enabling examples for the final result tool.
• Decorators: Updated Agent.tool, Agent.tool_plain, and FunctionToolset methods to accept examples.
• Anthropic Integration:
  • Maps examples to input_examples in the Anthropic API payload.
  • Beta Headers: Automatically detects the client type to send the correct beta header:
    • advanced-tool-use-2025-11-20 for standard Anthropic API.
    • tool-examples-2025-10-29 for Amazon Bedrock and Google Vertex AI.

Test Plan

• Added generic tests in tests/test_tools.py verifying examples can be set via Tool, decorators, and ToolOutput.
• Added specific tests in tests/models/test_anthropic.py verifying:
  • The mapping of examples -> input_examples.
  • The correct beta header is applied based on the underlying client type (Standard vs Bedrock/Vertex).

Related

• Add examples field to ToolDefinition and send it to Anthropic #3619
• Anthropic advanced tool features - Tool Use, Tool Search and Programmatic Tool Calling #3666