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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real value on top: every line carries an evidenceId for citation and the record is pre-counted so the agent shouldn't recompute it. That citation and pre-aggregation guidance is the kind of context annotations cannot convey.

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?

Three sentences, front-loaded with what is returned and followed by citations and the calling trigger. Minor awkwardness in 'the record, which is already counted,' but no filler.

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?

Even with seven parameters and no output schema, the description covers return contents (lines with evidenceIds, record, period matches, next matches) and the calling condition, while the fully documented schema handles the filtering details. Adequate for an agent to invoke correctly.

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 100%, so parameters like date, phase, season, and includeAllSeasons are already well explained in the schema. The description adds only a light hint about the whole-history scope; baseline 3 applies when the schema carries the semantics.

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?

Specific verb and resource: returns recorded lines, the team's already-computed record, every match in the period, and upcoming matches for a named team across any league/season. That scope meaningfully separates it from narrower siblings like query_match_log or query_team_forecast, though no sibling is named explicitly.

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?

States a clear trigger: when someone asks about a named team's matches, results, or next match, or before asserting a fact about them. It lacks explicit when-not guidance or a named alternative for adjacent questions (e.g., forecasting vs. results), so it stops short of a 5.

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