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

Annotations already declare this as a safe, closed-world read. The description adds real operational context beyond them: one page per seven-day window, a 366-day maximum range, cursor continuation including empty pages, and a Beijing-time source with an explicit warning that scores are not normalized to 90 minutes, extra time, or penalties. These are exactly the behavioral traits an agent would otherwise have to discover by trial and error.

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 a single dense paragraph where every clause carries information: scope, parameter formats, pagination rule, and the interpretation caveat. It is front-loaded with purpose, though the cursor naming slip and the run-on pagination sentence slightly reduce clarity.

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?

With no output schema, the description should explain return values, and it partially does by naming the has_more and next_cursor fields and their continuation semantics. It does not describe the result record shape (teams, score fields) or what limit controls, leaving a modest completeness gap for a five-parameter paginated query tool.

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?

Schema description coverage is 0%, so the description carries the burden, and it does explain query (competition or team keyword) and the YYYY-MM-DD format plus 366-day cap on date_from/date_to. Two gaps remain: the limit parameter is never mentioned, and the text refers to next_cursor while the schema parameter is named cursor, which risks a malformed follow-up call.

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 states a specific verb and resource plus scope: querying historical football match scores since 2021. It is clear what the tool returns, but it never distinguishes itself from the sibling get_fixtures, which an agent could plausibly confuse with this tool for match-level data.

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?

Usage is implied rather than stated: you pass a competition or team keyword plus a date range. The pagination loop is spelled out (continue with the same parameters whenever has_more=true, including empty pages), but there is no guidance on when to pick this over get_fixtures or get_data_coverage, and no exclusion cases.

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