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

Annotations already declare readOnlyHint and openWorldHint, yet the description still adds real behavioral value: the source does not paginate and histories can exceed a thousand rows, which warns the agent about payload size and the impossibility of chunked retrieval. It also states the result is 'complete' (no filtering), so the agent knows the cost up front.

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 tight sentences: capability first, prerequisite second, caveat plus alternative last. No filler, and the high-cost warning is placed where it will be read before invocation.

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?

An output schema exists, so return values need not be described, and the description covers provenance, non-pagination and the correct sibling for player stats. Minor gap: ordering of the history and whether there is any way to narrow the result set are not stated.

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?

With 100% schema description coverage on a single required parameter, the schema already documents 'positive OpenDota team ID from opendota_teams or a match response', and the description largely restates that provenance and positivity constraint. No added format or edge-case guidance (e.g. invalid or inactive team IDs) beyond the schema.

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 ('Returns the complete OpenDota match history for one team') and enumerates the payload fields (league, opponent, score, winner). It distinguishes itself from opendota_match, but not from other team-scoped siblings such as opendota_team, opendota_team_players, or opendota_league_matches.

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?

Gives a clear precondition (needs a positive team_id, sourced from opendota_teams or a match result) and names an explicit alternative for a different need (opendota_match for parsed player statistics). It stops short of saying which sibling to prefer when the agent wants recent form, league listings, or aggregate team stats.

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