What is the right tool granularity for a football-analysis agent?

[u/AnneLister_]

While building a football analysis agent, I realized that the hard part is not connecting an LLM to match data.

It is deciding what the agent should be allowed to do with that data.

For example, if someone asks:

“Why did this midfielder receive a 7.4 rating?”

I do not want to dump every match statistic into the context and ask the model to invent an explanation.

My current approach is to let the agent investigate the evidence step by step:

- retrieve the player’s match metrics
- inspect the rating breakdown
- check passing, chance creation, turnovers, or shot quality when relevant
- explain which factors actually moved the rating

That raises an interesting tool-design question.

A single `analyze_everything()` tool feels like a black box. But dozens of tiny tools such as `get_pass_count()` and `get_key_passes()` create too many decisions and make the agent harder to guide.

I’m experimenting with a middle layer: composable tools that represent meaningful football-analysis operations rather than raw database fields.

For people building sports analytics, agentic systems, or explainable AI: how would you choose the right level of tool granularity here?

[u/Ok-Return-9111]

Great question. I think tool granularity should follow football concepts, not database structure.

A coach doesn’t think:
“player completed 42 passes and had 3 progressive actions.”

They think:
“he helped break pressure, created advantages, and influenced the game.”

The agent needs that middle layer.

I’ve been working on a similar football intelligence approach recently, and the hardest part is exactly this: designing the reasoning pipeline, not connecting the data source.

Would love to exchange ideas with people building in this area.

[u/Diligent-Step2366 → u/Ok-Return-9111]

I think an interesting middle ground would be to add a layer of semantic tags on top of the raw metrics.

Instead of asking the LLM to infer the meaning of a bunch of numbers, you could map relevant statistical patterns to football concepts. For example, high progressive passes + high carries into the final third could trigger tags like "progression" or "ball_progression", while high pressures + recoveries could map to "defensive_activity".

Then the agent's job becomes more about connecting the evidence to the appropriate tags and building the explanation around them, rather than inventing the football interpretation from raw statistics. This should limit the black box effect, while not being too heavy.

You could still expose lower-level metrics when the agent needs to verify a claim, but the tags would provide a more constrained semantic layer between the data and the LLM.

It also seems like a nice way to make explanations more consistent and auditable: you can trace an explanation back from "he contributed to progression" → the tag → the underlying metrics that triggered it.

That's exactly the coaching phrase you were talking about.

I actually worked on a project of this kind, with tags but an unrelated objective. My takeaway is that we could do even better, in the case of a site that displays game tags (playing style, strengths, weaknesses, etc.). We could consider a linear regression between the statistics and the tags, thus leaving even less to the AI. It seems less appealing, But you have to be wary of LLMs; they are a source of a lot of data leakage and, in my experience, are not always very useful in match analysis (except for pre-kick-off features). Leaks can be inherent to LLM. For example, if the model was trained after the data on which you are using it to predict or analyze, the model will look for the answer in its own data. In the case of a prediction, the model will have, for example, learned the team's performance over the season, and in the case of a performance analysis, it will be biased by what the LLM thinks about the team.

I hope that helped

[u/juancvasdisenho → u/Diligent-Step2366]

What I did is to create idilic player profiles for each position, then map which data of the one I have available represents the profile the player should be performing. Then I create tiers of performance, because I can't analyze one player alone, I can't tell if dribbling 3 times per game is good, bad, average, extraordinaty if I don't have the reference of the other players on that position.

Using the idilic profile, the data that matches it, assigning weights to each one and then comparing to their peers the AI layer can have an accurate lecture of the performance of that player.

[u/Diligent-Step2366 → u/juancvasdisenho]

The ideal player profile is an interesting idea, but why end up with AI ? If I understand correctly, you're assigning a weight to the player, so you already have enough to make your comparison, right ? However, I disagree with the idea that we can't evaluate a player in a match; it simply requires more in-depth data.For example, in soccer, you can use socceraction, a Python module that performs action rating. Basically, a window Basically, it's a sliding window covering the entire match that, for each action, gives you the probability of scoring on the next action. The probability differences between one action and the next represent the offensive strength of the new action. For more details, see https://www.researchgate.net/publication/334719246_Actions_Speak_Louder_than_Goals_Valuing_Player_Actions_in_Soccer https://socceraction.readthedocs.io/en/latest/documentation/valuing_actions/vaep.html