Search SofaScore's credential-free public JSON for teams, players, and competitions from a free-text query; returns matches or an empty results list.
SofaScore universal search. Searches SofaScore's credential-free public JSON for teams, players, and competitions matching a free-text query. An empty results list is a valid response when nothing matches.
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Free-text search query |
Changes observed during successful MCP inspections.
v1.5.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It mentions 'credential-free public JSON' and that an empty results list is valid, but it does not address rate limits, pagination, or response structure. This is insufficient for full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. It efficiently conveys the tool's purpose, data source, and valid response behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search with one parameter and no output schema, the description is reasonably complete. It specifies what is searched (teams, players, competitions) and that an empty result is valid. However, it could mention if results are ordered or any default limits.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'q' is fully described in the schema ('Free-text search query'). The description does not add additional meaning beyond the schema, so it meets the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool performs a 'universal search' for teams, players, and competitions, with a clear verb ('searches') and resource ('SofaScore's...JSON'). It distinguishes from siblings like sofascore_event and sofascore_team by being a general-purpose search across multiple entity types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for general search but does not specify when to use it over specific entity tools (e.g., sofascore_team, sofascore_event). No exclusions or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.