docs: Update tool docs

[sjrl]

Related Issues

• fixes #issue-number

Proposed Changes:

• Updated tool docs to update stale doc strings that didn't fully reflect all features currently available (E.g. tool decorator and create_from_function differences).
• Added tips and notes to suggest to users preferred ways of creating tools and using tools.
• Updated example model in examples to gpt-5.4-nano instead of gpt-5-nano.
• Updated examples to use the recommended tool creation where relevant.
• Updated additional resources section to include more recent tutorials on agents.

How did you test it?

Ran code blocks locally to make sure they worked.

Notes for the reviewer

The inspiration for this update was to help users and agents identify recommended patterns for tool use in Haystack.

Checklist

• I have read the contributors guidelines and the code of conduct.
• I have updated the related issue with new insights and changes.
• I have added unit tests and updated the docstrings.
• I've used one of the conventional commit types for my PR title: fix:, feat:, build:, chore:, ci:, docs:, style:, refactor:, perf:, test: and added ! in case the PR includes breaking changes.
• I have documented my code.
• I have added a release note file, following the contributors guidelines.
• I have run pre-commit hooks and fixed any issue.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
haystack-docs	Ready	Preview, Comment	May 4, 2026 11:35am

[claude]

Code review

Issue: Invalid OpenAI model name gpt-5.4-nano

The PR replaces gpt-4o-mini and gpt-5-nano with gpt-5.4-nano across 8 code examples in both modified files. OpenAI does not have a model named gpt-5.4-nano — OpenAI's naming convention does not use minor decimal version numbers in the form 5.X (real models follow patterns like gpt-4o, gpt-4o-mini, gpt-5, gpt-5-nano). Users copy-pasting these examples will receive a model-not-found error from the OpenAI API.

The affected lines appear in docs-website/docs/tools/tool.mdx and the mirrored versioned file — for example:

chat_generator = OpenAIChatGenerator(model="gpt-5.4-nano", tools=[add_tool])

Suggested fix: Replace gpt-5.4-nano with a real model such as gpt-5-nano (or gpt-4o-mini to restore the original value).

---

🤖 Generated with Claude Code

[sjrl]

Code review

Issue: Invalid OpenAI model name gpt-5.4-nano

The PR replaces gpt-4o-mini and gpt-5-nano with gpt-5.4-nano across 8 code examples in both modified files. OpenAI does not have a model named gpt-5.4-nano — OpenAI's naming convention does not use minor decimal version numbers in the form 5.X (real models follow patterns like gpt-4o, gpt-4o-mini, gpt-5, gpt-5-nano). Users copy-pasting these examples will receive a model-not-found error from the OpenAI API.

The affected lines appear in docs-website/docs/tools/tool.mdx and the mirrored versioned file — for example:

chat_generator = OpenAIChatGenerator(model="gpt-5.4-nano", tools=[add_tool])

Suggested fix: Replace gpt-5.4-nano with a real model such as gpt-5-nano (or gpt-4o-mini to restore the original value).

🤖 Generated with Claude Code

Claude be wrong. https://developers.openai.com/api/docs/models/gpt-5.4-nano

[anakin87]

👍