Document performance implications of async vs sync tools

[GuillermoBlasco]

Added minor change to documentation so specify the requirements for tools to be concurrently executed.

Slack conversation reference: https://pydanticlogfire.slack.com/archives/C083V7PMHHA/p1753301883710229

[hyperlint-ai]

PR Change Summary

Specified the requirements for concurrent tool execution in the documentation.

• Clarified the need for tools to be defined as async functions for concurrent execution.
• Emphasized the use of non-blocking clients for effective concurrency.

Modified Files

• docs/tools.md

---

How can I customize these reviews?

Check out the Hyperlint AI Reviewer docs for more information on how to customize the review.

If you just want to ignore it on this PR, you can add the hyperlint-ignore label to the PR. Future changes won't trigger a Hyperlint review.

Note specifically for link checks, we only check the first 30 links in a file and we cache the results for several hours (for instance, if you just added a page, you might experience this). Our recommendation is to add hyperlint-ignore to the PR to ignore the link check for this PR.

[DouweM]

@Kludex Can you please check this out? You had some related comments in our internal Slack that I think should also be documented.

[GuillermoBlasco]

BTW Alex Hall commented in the public Slack about documenting a bit how to use the baggage to add attributes in the spans of an agent run. I was about to document this also, do you care if I add that bit to this PR?
https://pydanticlogfire.slack.com/archives/C06EDRBSAH3/p1753133127281339

[DouweM]

@GuillermoBlasco I'd prefer to have that in a separate PR.

---

As for the thing I pinged Marcelo for, he's going to be out next week, so I'll quote it here so you can see if you can incorporate it into this PR yourself:

[Other person]

Is it general good practice to have all tools async?

Marcelo Trylesinski

in general, if your tool just returns a value without any blocking io, yes

if you use anything that is blocking io, like non-async http call, file reading, etc, then def is the way to go

underneath it will run in a different thread

so if you have just

def simple():
   return 1

it's better to be async

same concept in FastAPI

[Other person]

Ahh interesting I would have expected the opposite, I guess you don't know if def is quick or slow, hence using the different thread.

Marcelo Trylesinski

yep

[Other person]

Does that also apply for @agent.instructions?

Marcelo Trylesinski

yep

[GuillermoBlasco]

Docs updated with the detail Marcelo provided!

[Kludex]

I would prefer to not have the "using asyncio.create_task" in this sentence.

That's an implementation detail, which I don't think is correct (and if it is, we might need to change it).

[DouweM]

@Kludex Can you remove/reword it please?

[Kludex]

Can @claude do it?

[Kludex]

This is okay.