docs: document tool decorator alias

[william-xue]

Summary

• recommend the new agents.decorators.tool alias in the function-tools guide
• update the primary example while clarifying that function_tool remains supported
• add the decorators module to the API reference

This follows the documentation work deferred from #3920 and makes the new public alias discoverable.

Test plan

• uv run mkdocs build
• import/configured-decorator smoke test with uv run python
• git diff --check

Issue number

Follow-up to #3920

Checks

• I've added new tests, if relevant (not relevant; documentation only)
• I've run .agents/skills/code-change-verification/scripts/run.sh (not required for docs-only changes)
• I've confirmed all verification steps pass
• If using Codex, I've run /review before submitting this PR

[seratch]

Thanks for sending this. We'll handle the change in #3872