getPredictionMatchList

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only nature is covered. The description adds value by specifying what the response contains: teams, scheduled time, match status values, and associated prediction markets. It also clarifies that matches are scoped to a sports event and that eventId is the link to further market detail.

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 front-loaded with the core purpose and includes useful agent hints. There is some redundancy between the first sentence and the second sentence, both describing status and prediction market info, but the additional usage guidance and explicit do/don't rules justify the length.

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 single-parameter read-only tool with no output schema, this description covers purpose, return contents, status semantics, the downstream eventId usage, and a safety rule about Ended matches. The only notable gap is that 'Filter by matchStatus' could be misinterpreted as an API parameter, since the schema only accepts eventType.

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 input schema provides only an enum of '1' with no description, so schema coverage is 0%. The description compensates by explicitly mapping eventType=1 to FIFA 2026 and explaining the practical use of the parameter. It also clarifies that matchStatus filtering is a client-side concept rather than an API parameter, though this could be stated more explicitly.

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?

States a specific verb and resource: query all matches for a sports event, with current status and prediction market info. The description also differentiates from related prediction tools by clarifying that it returns match-level eventIds for use with getPredictionEventDetail, not detailed token info itself.

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?

Provides clear context on when to use the tool: to show users available matches to bet on, and as a precursor to calling getPredictionEventDetail. It also gives actionable filtering guidance by matchStatus and explicitly warns against showing Ended matches for trading unless requested. It does not name alternative tools for other scenarios, but the use case is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.