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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds useful behavior beyond that: the text is plain text capped at 6000 characters and is site content. It does not mention error behavior for invalid ids, which is the only remaining gap.

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?

Two short sentences: the first defines the output, the second defines when to reach for it. Front-loaded, no filler, and every clause carries information.

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 one-parameter read tool with no output schema, the description fully covers what is returned, when to use it, and the truncation limit. Nothing an agent needs in order to call it correctly is missing.

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 coverage is 100% and the single parameter is documented as coming from v3_news or v3_search. The description adds nothing further about the id, so the baseline 3 for full schema coverage applies.

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 ('Read one news story') and enumerates what comes back: title, publish time, full text, tags, and the match. The 'one story' scope clearly separates it from the list-making sibling v3_news.

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?

Explicitly names the two alternatives (v3_news, v3_search) and the condition that selects this tool: the user wants the story itself rather than the headline. An agent has a concrete decision rule without opening any schema.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior, but the description adds non-obvious implementation detail: Varzesh3 has no head-to-head page, so it scans the last depth*24 matches of team_id across all competitions for the opponent. That reveals a bounded-scan limitation an agent would otherwise miss. It omits what happens when the opponent never appears in the scanned window.

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?

Front-loads the core purpose in the first sentence, then adds only the details an agent needs (scan mechanics, id discovery, id handoff to v3_match). Every sentence earns its place with 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?

With no output schema, the description correctly indicates what comes back: a list of meetings, each with an id usable by v3_match, plus a won/drawn/lost summary for team_id. Only the empty-result case is left unaddressed.

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 coverage is 100%, so the baseline is 3, but the description adds real meaning: depth is a scan budget you raise to look further back, and the scan covers all competitions for team_id. That clarifies the cost/recall tradeoff of depth beyond the schema's 'pages of 24 past matches' phrasing.

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: 'Get the past meetings of two football teams with a won/drawn/lost summary for team_id.' This clearly separates it from v3_team_matches (one team) and v3_match (single fixture).

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 concrete query examples ('Perspolis vs Esteghlal history', 'last derby results') and explicit routing: 'Find ids with v3_search. Each meeting has an id for v3_match.' It also explains when to raise depth, which is actionable guidance rather than vague context.

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

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

Annotations already cover read-only, idempotent, open-world and non-destructive traits, so the description focuses on behavior beyond that: the ID list is a curated 'short menu' but external league ids from v3_scores are accepted, season winners are returned only for football, and the sport argument is shared with three sibling tools. It stops short of describing pagination, ordering, or rate limits, keeping it at a 4.

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?

Front-loaded with the core dual-mode statement, then the routing and sport details. Dense but every clause carries information; the parenthetical id examples are numerous enough to border on clutter, which keeps it from a 5.

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 must convey returns, and it does: league ids in list mode, season ids and past winners in detail mode. It leaves the exact response shape (field names, ordering) unspecified, a minor gap for a two-parameter lookup 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 coverage is 100%, so the baseline would be 3, but the description adds real meaning: omitting league_id yields the listing mode, and concrete id examples (6 Iranian Pro League, 55 Portuguese, 209 NBA) plus per-sport id mappings clarify what the enum and integer values denote. It exceeds the schema rather than restating it.

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 in both modes: list leagues with their ids, or fetch one league's current season id and past seasons with winners. The dual behavior is tied explicitly to the presence of league_id, so an agent can distinguish it from siblings like v3_standings or v3_league_stats without opening a schema.

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?

Explicit routing guidance: call without league_id to discover ids for v3_standings, v3_league_matches, v3_top_players and v3_news, and it notes that any league_id surfaced by v3_scores is also valid. It also states that the other tools default to the current season, which tells the agent when this tool is needed instead of them.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: results are returned round by round, paging moves one round at a time, and each match carries an id for v3_match. It says nothing about result volume, ordering within a round, or limits beyond the schema's skip maximum, so the addition is useful but not rich.

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 short sentences, front-loaded with what the tool returns, followed by usage examples and the paging recipe. Every sentence carries information an agent needs; there is no filler or repetition of the schema.

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 does cover the essentials of the return value (round-by-round scores and dates, match ids for follow-up) and the paging model for a five-parameter read tool. It stops short of describing how rounds are grouped or ordered in the response, which would matter for an agent assembling multiple pages.

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 coverage is 100%, so the baseline is 3, but the description genuinely adds meaning the schema does not: skip=9 corresponds to roughly one round, and the which values are meant to be used in a current-then-page sequence. That operationalizes two of the five parameters rather than restating their enum definitions.

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 ('Get a league's matches round by round') plus what is returned (scores of played rounds, dates of upcoming ones), which is enough to separate it from v3_match and v3_team_matches. It does not explicitly contrast itself with v3_scores, whose name overlaps with the 'scores of played rounds' phrasing, so the sibling differentiation is implied rather than stated.

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 concrete user-intent examples ('next round of La Liga', 'results of week 10') and an explicit call sequence: start with which="current", then page with which="upcoming" or "results". It lacks an explicit when-not or a named alternative (e.g. v3_team_matches for a single club), so it stops short of full routing guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world read behavior, so the safety profile is covered. The description adds behavior beyond that: the default result shape is top-3 boxes per category unless the ranking parameter is set, and it points to v3_league as the source of league_id/season_id. It does not discuss pagination, volume of ranked results, or season defaults beyond what the schema states.

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?

Two short blocks with the concrete capability stated first and routing guidance second; every sentence carries information. Slightly loose formatting (the mid-sentence line break) and the parenthetical metric list is longer than strictly needed, but there is 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?

There is no output schema, so the description must convey what comes back; it does so by enumerating the statistical categories and explaining the top-3 default versus full ranking. Combined with a fully documented 3-parameter schema, an agent has enough to call it correctly; only the exact response shape per category is unspecified.

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% — ranking, league_id, and season_id are all documented in the schema, including the enum values and the top-3-vs-full-ranking distinction. The description reinforces the ranking semantics and lists the categories, but adds no new syntax, format, or edge-case meaning beyond the schema. Baseline 3 applies.

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?

Opens with a specific verb+resource ("Get a football league's season statistics") and enumerates the concrete outputs: goals per match, cards per match, goal timing, streak notes, team rankings. It also names the sibling it is not (v3_top_players), so an agent can distinguish it from the player-oriented tools without opening schemas.

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 concrete natural-language query examples ("most clean sheets", "how many goals per match in the Iranian league") that map user intent to this tool, plus an explicit fallback rule: without ranking you get the top 3 in each category. The only gap is that it doesn't distinguish this from the sibling v3_standings (league table) or v3_league_matches, which an agent could plausibly confuse it with.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the description's added value is data-availability context: lineups appear only near kick-off, Varzesh3 lacks per-match possession/shot stats, and sport changes the returned shape (quarter points, set scores). It does not discuss error behavior for invalid ids, so it falls slightly short of the top mark.

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?

Front-loaded with the resource and its payload before moving to usage and sport-specific caveats, and every clause carries information. Slightly dense and list-heavy, but nothing is 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?

There is no output schema, so the description carries the burden of describing return values, and it does so thoroughly across football, basketball and volleyball, plus the events decoding (own goals, second yellows, VAR, shoot-outs). An agent has enough to call it and to predict the response shape.

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 coverage is 100%, so the parameters are already documented; the description still adds meaning by explaining that sport alters the returned data per discipline and that prediction=true appends the fans' poll with shares expressed as percentages. This goes beyond the schema, which only says 'add the fans' prediction poll'.

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 ('Get one match') and immediately enumerates the returned content: score, status, goals, cards, penalties, substitutions, lineups, referee, stadium, video, next matches. It also implicitly distinguishes itself from list-scoped siblings by noting it needs a match id that came from v3_scores or a list tool.

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 an explicit prerequisite ('Use it after v3_scores or a list tool gave you a match id') and routes a specific need elsewhere ('no per-match possession or shot statistics ... season averages per team: v3_league_stats'). It also warns that lineups only appear close to kick-off, which tells the agent when the tool cannot satisfy a request.

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

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: a section returns the newest ~60 items with news and videos mixed, the 'type' field distinguishes them, and videos open on video.varzesh3.com. It does not mention paging behavior or rate limits, keeping it short of a 5.

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?

Front-loaded with the core purpose, then examples, then sibling handoff and the section-return caveat — every sentence does work. Slightly undermined by the dangling reference to 'type' as an output field that is never explained or defined elsewhere.

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 six-parameter, multi-mode read tool with no output schema, the description covers modes, scoping rules, the article handoff, and the shape of section results. The main residual gap is paging (skip max 500, take max 30) and the unexplained 'type' value set, minor against an otherwise complete definition.

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 coverage is 100%, so the baseline is 3; the description earns above that by tying natural-language intents to concrete parameter combinations (e.g. wrestling → scope="section", section="Wrestling"), which is a mapping the schema alone does not supply. Paging parameters (skip/take) are not discussed, so it is not fully comprehensive.

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 ('Get Varzesh3 news headlines with a short summary') and enumerates the available modes (latest, most read, most commented, team/league/player/match/section). It also names the sibling that continues the workflow ('Call v3_article with a news id'), so it is clearly distinguishable from v3_article and v3_videos.

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 concrete intent-to-parameter mappings ('latest news', 'news about Esteghlal', 'wrestling news' → scope="section", section="Wrestling') and an explicit handoff rule to v3_article for full stories. Both when-to-use and which-alternative are stated, leaving little to inference.

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

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

The annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real context beyond that: what content the player page actually contains, and specifically that Varzesh3 keeps no career or season statistics there, which prevents a common misuse. It does not describe output shape or pagination, but no output schema exists and the returned field list partially compensates.

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?

Two short paragraphs: the first states what is returned, the second states when to call it and where to go instead. Every sentence earns its place and the essential scoping fact (no statistics here) is front-loaded before the alternatives.

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 carries return-value information and does so by listing the profile fields and mentioning news and videos. It also closes the main behavioral gap (absence of statistics). A minor omission is that the optional sport parameter (football/futsal) is never mentioned, though the schema documents it fully.

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%, and the schema already explains that player_id comes from v3_top_players, v3_team_players, match events or v3_search. The description repeats the same provenance point at a higher level ("after any tool gave you a player id") without adding format or constraint detail. Baseline 3 is appropriate when the schema does the heavy lifting.

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 uses a specific verb and resource ("Get a player's profile") and enumerates the fields returned (team, position, shirt number, age, country, latest news and videos). It also explicitly separates this tool from v3_team_players and v3_top_players by stating that statistics are not here, so an agent can distinguish it from its siblings without opening their schemas.

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?

It gives an explicit when-to-use trigger ("after any tool gave you a player id", "who is X", "news about X") and an explicit when-not-to-use plus alternative (for goals and assists use v3_team_players for the team or v3_top_players for the league). Both the positive condition and the routing alternative are named.

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

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

Beyond the read-only and idempotent annotations, it discloses league ordering, score orientation, status values, and the non-obvious meaning of "incomplete". Sport-specific scoring fields and the Tehran/Jalali day-rollover caveat provide additional behavior essential to interpreting live results correctly.

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?

Purpose and example intents are front-loaded, followed by sibling routing, result-size advice, output interpretation, and the temporal edge case. Although dense, each sentence earns its place; even the long "incomplete" parenthetical resolves a genuine ambiguity rather than adding 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?

With no output schema, the description supplies the missing result semantics, including match ids, ordering, score format, statuses, and volleyball and basketball scoring details. Together with the fully documented input schema, it gives an agent enough information to select, invoke, and interpret the tool, including the important day-boundary caveat.

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 schema already documents all six parameters, but the description adds meaningful operational context: team or league filtering keeps answers short, league ordering affects how capped results should be understood, and day=0 follows the site's Jalali-day switch rather than simply civil midnight. Most filter syntax, defaults, and limits still come from the schema, so the added parameter semantics are strong rather than exhaustive.

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 opening sentence specifies the operation, resource, source, and precise scope: live scores, results, and fixtures for one day across leagues on Varzesh3. The handoff to v3_match further distinguishes this day-level listing tool from match-detail retrieval.

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?

It explicitly maps the tool to intents such as "what is on today", "Perspolis result", and "live matches now". It also gives concrete alternative routing: pass a returned match id to v3_match when goals, cards, or lineups are needed.

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

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

Beyond the read-only, idempotent annotations, it discloses the important language limitation that English names usually return nothing. It also provides partial result behavior by explaining that `entities` contain team IDs of kind Team, though other result types are not described.

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 definition is compact and front-loads its purpose and ID-resolution role. Every subsequent clause earns its place by specifying the first-use workflow, downstream consumers, or the Persian-language constraint.

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 two-parameter search tool, the schema, annotations, and description collectively provide enough information to select and invoke it correctly. With no output schema, however, the player workflow is less complete than the team workflow: it does not identify the player entity kind or connect it to v3_player, and news/video result handling is likewise unspecified.

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 coverage is already 100%, including the Persian query requirement and the per-kind result limit. The description adds practical query semantics by warning that English names usually find nothing, rather than merely restating 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?

The description gives a specific verb, resource, and scope: searching Varzesh3 for teams, people, leagues, news, and videos by name. It also distinguishes the tool as the name-to-ID resolver feeding sibling tools such as v3_team and v3_team_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?

It explicitly says to use the tool first when the user names a team or player and identifies the downstream tools that consume a Team entity's ID. The Persian-search warning further guides how to formulate a successful request.

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

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

Annotations already establish read-only, idempotent, open-world behavior, and the description adds substantive return-shape detail on top: one table per group for group competitions, bracket output for cups, form as the last five results with oldest-first ordering and the latest match last, zones naming, and the volleyball-specific set/point columns. Since no output schema exists, this is exactly the kind of behavioral disclosure the description must carry.

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?

Front-loaded with the core action and return fields, followed by trigger phrases and then mode-specific caveats — a sensible order. There is mild redundancy between 'group tables' in the first sentence and the dedicated group sentence, plus an awkward line break mid-sentence, 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?

For a four-parameter read tool with no output schema, the description covers the return fields, both stage modes, multi-group competitions, form encoding and ordering, zone labels, and sport-specific column variants. An agent has everything needed to call it and interpret the response without further discovery.

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 coverage is 100% and both enums are already documented, so the schema does the heavy lifting. The description reinforces stage="knockout" for cups and explains the group-table behavior tied to stage, but adds little about sport or season_id beyond what the schema states (season defaults to current, sport defaults to football).

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 (get the table of a league) and enumerates the returned fields (rank, played, won, drawn, lost, goals, points, form), so the agent knows exactly what this produces versus fixtures-oriented siblings like v3_league_matches. It also distinguishes the two output modes (group tables, cup bracket), which makes it unambiguous against other v3_league_* tools.

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 concrete trigger phrases ('league table', 'who is top', 'how many points has X') and routes cups to stage="knockout", which is real when-to-use guidance. It stops short of naming alternatives (e.g., v3_league_matches for fixtures or v3_league_stats for aggregate stats) or stating exclusions, so it is clear context but not full routing logic.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety bar is met. The description adds real value beyond that by explaining the returned 'form' field semantics (last three results, W/D/L, newest first, all/home/away) – information no structured field carries. It stops short of describing payload size, pagination or error behavior.

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?

Front-loaded with the payload summary, then usage examples, then field semantics, then sibling routing – a sensible order with little waste. The board-split sentence and the redundant 'optionally transfers' phrase cost it a point.

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 carries the return-shape burden and does so for the non-obvious 'form' field, which is the main ambiguity. A brief note on what the response looks like for futsal teams, or on squad ordering, would close the remaining gap.

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% and each parameter (sport, squad, team_id, transfers) is already documented, including the futsal caveat. The description adds only the 'optionally transfers' note, which duplicates the schema default of false, so this is baseline territory.

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 ('Get a football team's page') and enumerates the payload (name, followers, recent form, squad by position, optional transfers). This clearly separates it from v3_team_matches, v3_team_players and v3_news, which are 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?

Gives concrete trigger phrases ('who plays for Esteghlal', 'latest signings') and routes the agent away to v3_team_matches for matches and v3_news with scope="team" for news. It does not say what to do when the team_id is unknown, though the schema points to v3_search/v3_standings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds useful behavior beyond that — results span all competitions and each returned match carries an id for v3_match — but says nothing about result shape, ordering guarantees beyond the schema, or empty-result handling.

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?

Two tight sentences: the capability is front-loaded, then usage examples and the downstream-link note follow. Every sentence earns its place with 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?

For a 4-param, fully documented, read-only list tool with no output schema, the description covers purpose, usage, and the id handoff to v3_match adequately. It could say slightly more about the return shape (e.g., score, date, competition fields), but nothing essential for correct invocation is missing.

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% and the enum for `which` already spells out the results/upcoming ordering, so the schema does the heavy lifting. The description only adds example team names in prose, which duplicates what `team_id`'s schema description already provides.

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 — a team's latest results or upcoming matches — and scopes it to 'across all competitions', which separates it from league-scoped siblings like v3_league_matches and from v3_scores. It also signals the handoff to v3_match via match ids, though it never explicitly contrasts itself with those siblings.

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 two quoted example queries ("Persepolis last 5 results", "when does Esteghlal play next") make the when-to-use condition concrete and map directly onto the `which` modes. There are no explicit when-not conditions or named alternatives for league-wide fixture lookups.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real value: it resolves the default season ('current season of the team's main league') and warns 'Players with a zero in the chosen stat may be missing', a subtlety that would otherwise be misread as absent data. Auth, rate limits, and pagination/limits are not mentioned.

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?

Front-loaded with verb, resource, and returned fields, then examples, then defaults and the sibling pointer; nearly every sentence earns its place. The dangling '`competitions` lists other leagues' clause is confusing wording that slightly undercuts an otherwise tight statement.

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 carries the burden and does reasonably well by naming the stats and warning about zero-stat omissions and defaults. It does not describe the result shape in detail (one row per player? sorted by stat?) or any result-size limits, which for a list-returning tool would be the remaining gap.

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 coverage is 100%, so 3 is the baseline; the description goes slightly beyond by explaining how the season default is resolved and how the `stat` choice affects which players appear in the result. It adds no meaning for `team_id` or `league_id` beyond what the schema already says.

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 ('Get the season statistics of one football team's players') plus the exact stats returned: goals, assists, appearances, minutes, cards. It is distinguishable from v3_player (single player) and v3_top_players (league-wide leaders) without opening any schema.

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 concrete triggering queries ('who scored for Perspolis', 'Esteghlal assists') and an explicit hand-off: 'Pass a player id to v3_player.' It does not explicitly distinguish this from v3_top_players or v3_league_stats, and the reference to '`competitions` lists other leagues' points at a field that is not in this tool's schema, which may confuse an agent.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so safety is covered. The description adds genuine behavioral context beyond that: it describes the returned record shape (player id, team, appearances, other season counters) and the important null semantics that 'a counter that is missing is zero'. It does not discuss pagination or how ties are ordered, which keeps it short of a 5.

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?

Front-loaded with the core verb+resource, then examples, then return shape, then the sibling routing — a sensible order. Slightly redundant in restating 'top scorers or most assists' which the stat enum description already covers, but nothing is bloated.

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 usefully characterizes the returned player records and the zero-default rule for missing counters. Combined with the fully documented 5-parameter schema, an agent has what it needs to call this correctly; only ordering/tie-breaking behavior is left implicit.

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%, and the enum descriptions already explain every stat value, the futsal limitation, and the league_id source. The description reinforces the 'one statistic' notion with examples but adds no syntax or constraint detail beyond the schema, so the baseline 3 applies.

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 — 'Get the best players of a football (or futsal) league by one statistic' — with concrete examples ('top scorers', 'most assists'). It also explicitly distinguishes itself from the sibling v3_team_players, so an agent can route correctly without opening either schema.

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 example user phrasings ('top scorer of the Premier League', 'most yellow cards') that map directly onto this tool, and names the alternative for a different intent: 'For one team's players use v3_team_players.' The when-to-use and when-to-use-something-else conditions are both explicit.

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

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive, so the safety profile is settled. The description adds genuine behavioral context beyond that: results are grouped club-by-club into arrivals and departures, omitting window_id yields the latest window, and narrowing by team_id reduces response size. It stops short of discussing pagination or limits, which the schema handles.

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?

Front-loads the core definition in one sentence, then moves to use cases and routing in a compact second paragraph. Slightly dense with quoted examples, but no sentence is wasted and the important scoping advice appears early.

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 six optional parameters, no required fields, and no output schema, the description does enough by explaining the returned structure (signed vs. left, per club) and the default of the latest window. Minor gaps remain around result ordering and whether the limit spans all teams, but the essential calling information is present.

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% and every parameter carries a clear enum or format note, so the baseline is 3. The description reinforces team_id narrowing and window_id sourcing from `windows`, but that information is already present in the schema descriptions, adding little new meaning.

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 ('Get the football transfer list of a window') and immediately defines the shape of the data ('club by club: players signed and players who left'). This is clearly distinguishable from siblings like v3_news, v3_team_players, and v3_search, which none of them cover transfer movements.

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 concrete example intents ('who did Esteghlal sign', 'all Iranian league transfers', 'loan deals') and an operational tip to filter by team_id to keep answers short. It also routes the agent elsewhere for related needs: `windows` for past window ids and `news` for headlines, which is explicit alternative-routing.

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

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

Annotations already declare read-only, idempotent, open-world behavior, so the description's added value is the 'next days' time window and the note that stream links open externally on anten.ir — useful operational context. It stops short of describing pagination or what happens when max_items is capped, but nothing essential is omitted.

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?

Front-loaded with the core capability in the first sentence, followed by example intents and the routing note. Slightly busy with the parenthetical Persian gloss and the anten.ir aside, but every sentence carries actionable information.

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 usefully explains what comes back (start times, stream links, match_id linkage). Combined with complete parameter documentation and annotations, an agent has enough to call and interpret the tool, though response shape is described only loosely.

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 both parameters are already fully documented in the schema, giving a baseline of 3. The description adds only an implicit hint that query text is Persian (already stated in the schema) and does not elaborate on max_items behavior.

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?

Names a specific verb and resource — 'live broadcast schedule of sports matches' — plus the key payload (start times, stream links). This clearly separates it from sibling tools like v3_scores (results) and v3_match (match 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?

Provides concrete example intents ('which matches are on live today', 'when is the Liverpool game broadcast') and an explicit hand-off rule: match_id goes to v3_match. It does not explicitly say when NOT to use it versus v3_scores or v3_news, but the context is clear enough to route on.

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

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

Annotations already declare read-only, idempotent, non-destructive and open-world, so safety needs no restating. The description adds return-shape context the annotations cannot: every video carries a page url on video.varzesh3.com, which matters because there is no output schema. Paging behavior and default page size are left entirely to the schema.

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 short sentences, front-loaded with purpose, then usage examples, then return detail. Nothing is repeated from the schema and no sentence is padding.

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 five-parameter, read-only listing tool with fully documented parameters and no output schema, the description covers purpose, selection guidance and the key returned field. Minor gaps: no mention of pagination limits (take max 30) or what happens when scope is scoped but id is null.

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 coverage is 100%, so baseline is 3, but the description earns above that by explaining scope/id coupling in plain language ('about one team, league, match or player') and reinforcing that scoped queries require an id. It does not, however, add anything for skip/take/sport beyond what the schema already documents.

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?

Opens with a specific verb and resource ('Get Varzesh3 videos') and enumerates the content types (goals, match summaries, interviews) plus the retrieval axes (latest, team, league, match, player). No sibling tool covers video content, so the resource alone differentiates it from v3_news, v3_match and the rest.

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 concrete natural-language-to-call mappings ('highlights of the Perspolis match' -> scope="match" with the match id; 'latest goals'), which tells the agent when this is the right tool. It stops short of stating exclusions (e.g. use v3_news for written coverage), but no sibling really competes for video lookups.

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