442ball

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds freshness semantics ('latest weekly') and the returned field set, but says nothing about unknown-slug behavior, error shape, or how often the weekly snapshot rolls over.

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?

A single front-loaded sentence that leads with what is returned, then lists the payload and closes with the input prerequisite. No filler, and the ordering matches how an agent decides to call it.

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?

No output schema exists, and the description compensates by enumerating the return fields; the single input's origin is also explained. What remains unstated is failure behavior for an invalid or unknown club slug, which matters for a one-required-param lookup.

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 0% (only a regex pattern is declared), so the description carries the burden and does so: it identifies the parameter as a club slug and names resolve as its source. It does not restate the slug format, but the source hint is the more useful information.

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 one club's latest weekly 442ball Power Rating) and enumerates the payload: rating, band, league rank, attack/defence indices, long-run rating, plus club and league URLs. The 'latest weekly' + 'one club' framing distinguishes it from siblings like rating_history (time series), rankings and league_strength (league-wide).

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?

'Takes the club slug from resolve' gives an explicit prerequisite and routes the agent to the sibling that produces the input. It does not state when to prefer rating_history or compare_clubs instead, so there is clear context but no exclusions.

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=true and openWorldHint=false, so safety is covered. The description adds value beyond that: it scopes the data source ("from the results 442ball holds"), the temporal windows (longest this season and since 2010), and explicitly sets output granularity with "Run lengths only" – preempting an agent from expecting match lists.

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 front-loaded sentences: what is returned, its scope, and the output limit, then the input dependency last. No restatement of the title and 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 read-only single-parameter tool with no output schema, the description covers return content, data source, time windows, and input provenance. Minor gaps remain: it does not say what happens for an unknown slug or whether a club with no runs returns empty values.

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 must carry the parameter. It does the most useful thing possible: names the parameter's source (the slug from resolve) and by implication its form, compensating for the bare pattern-only schema. It stops short of documenting the slug pattern or error behavior, so not a 5.

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 one club's current and longest runs"), then enumerates the exact run types: unbeaten, winning, winless, clean sheets, overall/home/away. The qualifier "one club's" implicitly separates it from the sibling league_runs, 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?

"Takes the club slug from resolve" gives an explicit prerequisite and points to the exact sibling tool that produces the input, which is the critical usage instruction here. It does not state when to prefer league_runs or compare_clubs instead, so it falls short of full when/when-not 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 cover the safety profile (readOnly, non-destructive, closed-world), so the description earns credit for extra behavior: the difference is only emitted when both ratings share a scale, and otherwise the response explains why it is withheld. That pre-empts a confusing partial result. Return shape beyond that (fields, ordering) is 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?

Three short sentences, front-loaded with the return value, then the conditional behavior, then the parameter source. Nothing is redundant and every sentence adds 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 simple two-parameter read with no output schema, the description covers what is returned, the conditional withholding rule, and the parameter provenance — enough for correct invocation. Minor gap: no hint about what the response contains when the difference is withheld or how ratings are labeled per club.

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 must compensate, and it does the most important part: both parameters are club slugs sourced from resolve, not free-text names. It does not restate the slug pattern or clarify ordering of club_a vs club_b, but the critical type/derivation is covered.

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 two clubs' latest 442ball Power Ratings side by side') and makes the two-club comparison scope unmistakable, which cleanly separates it from the single-club sibling club_rating and the list-style rankings/league_index 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?

The clause 'Takes two club slugs from resolve' establishes the prerequisite step (resolve the clubs first) and is genuinely useful routing context. However, it never says when to prefer this over club_rating called twice, nor any exclusion or failure condition beyond the withholding rule.

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, non-destructive and closed-world, so the description's job is added context — and it delivers: finished seasons only, the since-2010/11 (or league's first recorded season) cutoff, ranking basis (league results), and the no-cross-league-comparison invariant. It doesn't cover what happens if both club and scope are supplied, which would be the remaining behavioral unknown.

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?

Return fields are front-loaded, which is good, but the two operating modes and their differing count limits are packed into one long semicolon-joined sentence with stacked parentheticals. Nothing is wasted, yet the mode split would scan far better as two separate statements.

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 and 0% parameter coverage, the description does the heavy lifting by listing returned fields and both modes. Still missing: the parameter-name mapping for the league slug, behavior when both 'club' and 'scope' are passed, and whether results are ordered by score or rank.

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 0%, so the description must carry all parameter meaning. It does explain counts and defaults (1–20, default 10 for leagues; 1–10 for clubs) and that slugs come from resolve, but it never names the 'scope' parameter — an agent must infer that the league slug goes into 'scope' rather than 'club'. That implicit mapping is the key gap at zero schema coverage.

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 (returns club-seasons ranked within one league) and enumerates the return fields: score, league rank, longest unbeaten run, club page URL. It also names its two modes (league-wide vs. one club's best seasons), which separates it from generic siblings like rankings or league_runs, 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?

It gives clear operating conditions: finished seasons only, never compares sides across leagues, league slug comes 'from resolve' (an implied prerequisite call to a named sibling), and count bounds differ per mode. It stops short of explicit when-not-to-use-this-tool guidance or naming a substitute tool for adjacent questions.

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=true, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds genuinely non-obvious behavior: the returned payload includes both formula components, a league page URL, and a European rank that is absent for non-European leagues. It stops short of describing error behavior for an invalid slug.

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?

Content is front-loaded with the core purpose before the formula, and every clause carries information. The single dense sentence packing formula, defaults, bounds, and rank rules is heavy to parse, but little is wasted.

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 takes on the burden of explaining return values and does so: components, rating points, page URL, and rank presence. It is nearly complete for a 2-parameter read tool, with only failure modes and parameter-interaction precedence left unstated.

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 must carry the load, and it largely does: `league` is identified as a slug obtained from resolve (explaining the regex), and `n` is described as the count of top European leagues with a default of 10 and range 1–20. The implied either/or relationship between the two parameters is conveyed but not stated 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?

The description names a specific verb+resource ('Returns the 442 League Index') and spells out the exact composite formula, so an agent knows precisely what value comes back. It does not differentiate itself from the similarly-named sibling league_strength or rankings, which leaves ambiguity about which metric to prefer.

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 only implied: the parenthetical '(its slug from resolve)' signals that resolve must be called first to get a slug, and the default/bounds for `n` are stated. There is no explicit statement of when to use this versus league_strength or rankings, and no guidance on what happens if both `league` and `n` are supplied.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds modest context — default of 5, hard cap of 10, and inclusion of page URLs — but says nothing about freshness of 'current' runs or what happens when a league has no qualifying clubs.

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?

One sentence, front-loaded with purpose, then the kind enumeration, count bound, return shape, and the resolve dependency. 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 three-parameter read-only query with rich annotations and no output schema, the description covers what is returned and the one input an agent cannot guess (league slug provenance). Slightly incomplete on edge-case behavior but adequate to call 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 0%, so the description must carry parameter meaning; it partially does by explaining that league is a slug obtained from resolve, while kind and n are only restated from the schema (enum values and 1-10/default 5 are already structured). The league slug format itself is not elaborated beyond its source.

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 clubs of one league with the longest current run' — and enumerates the four kinds, the count range, and the per-club page URL. The scope 'of one league' implicitly separates it from the per-club club_runs sibling.

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?

'Takes the league slug from resolve' gives a clear prerequisite and names the sibling tool that supplies the required parameter. It stops short of stating when to prefer this over club_runs or league_strength, so there are no explicit exclusions.

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=true, openWorld=false, destructive=false, so the safety profile is covered. The description adds value beyond them by disclosing the freshness semantics ('latest weekly') and, since there is no output schema, that the response includes club count and a league page URL.

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 with no filler; what the tool returns is front-loaded before the input hint. 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 single-parameter read with no output schema, the description is nearly sufficient: it names the returned contents and the input source. It could say slightly more about what the strength value itself represents (units/scale), which is the only 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 0%, so the description must carry the load; it does by identifying the parameter as a league slug and, crucially, stating that it comes from the resolve tool. It leaves the slug character format to the schema's regex, which is acceptable.

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 one league's latest weekly 442ball league strength') with clear scope ('latest weekly') and names the returned fields (club count, league page URL). The word 'strength' plus 'latest weekly' cleanly separates it from siblings like league_index, league_runs, and rankings.

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?

'Takes the league slug from resolve' explicitly routes the agent to the sibling that produces the required input, which is the main usage decision here. It does not state when to prefer this over league_runs/league_index, so it stops short of full 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 readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds real value by specifying the return is prose ('in words') covering three named topics, which tells the agent the shape of the content without an output schema. It does not state length or that no numbers/current ratings are returned, which would fully close the 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?

A single front-loaded sentence that names the action, the subject domain, and the three content areas with no filler. Nothing in it should be cut.

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 responsibility for describing the return, and it does by enumerating the topics covered and stating the output is textual. Minor gaps remain – no indication of length, of whether the current ratings are included, or of how to get the version value separately – but an agent can call this confidently.

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 tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the description correctly implies no arguments are needed to retrieve the methodology.

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 – it 'explains in words how 442ball calculates its club Power Ratings and league strength' – and enumerates the covered topics (band meaning, method version). This implicitly separates it from data-returning siblings like club_rating, league_strength, and rankings, which yield numbers rather than prose, though no sibling is named.

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 usage context is implied: call this when you need an explanation of the ratings rather than the ratings themselves. There is no explicit when-to-use or when-not-to-use statement, and no sibling is called out as the alternative for numeric 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 readOnlyHint, destructiveHint=false and openWorldHint=false, so safety is covered; the description adds real context on top: results are bound to the two most recent weekly snapshots and measure rating delta rather than absolute rating. It does not mention tie-breaking, ordering stability, or what happens if a league has fewer than n movers.

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?

A single dense sentence that front-loads the return, then layers scope, count, and the delta definition with no filler. Every clause carries information the agent needs to call the tool correctly.

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 is the only source for return shape, and it does say the tool returns clubs ranked by rating change with the delta as the metric. It stops short of enumerating the per-club fields (name, rating, change value), which is a modest gap for a tool with no structured return documentation.

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 0% schema description coverage, the description must carry the parameters and largely does: n is bounded to 1-10 with a default of 5, direction is glossed as rose (up) or fell (down), and scope is described as a league slug or a comparison group. The remaining gap is that it does not explain how the tool distinguishes a league slug from a comparison-group identifier in the same string parameter.

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 clubs whose Power Rating rose or fell most) scoped to the latest two weekly snapshots, which separates it semantically from rating_history (full series) and rankings (static list). The closing note that the change is the rating difference only further pins down what is being measured.

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 description makes the data window (latest two weekly snapshots) and scope choice (one league slug or one comparison group) clear, which implicitly tells an agent when this tool fits. However, it never names an alternative or states when not to use it, so the choice against siblings like rankings or rating_history is left 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?

Annotations already cover safety (readOnly, non-destructive, closed-world), so the bar is lower; the description adds freshness ('latest weekly snapshot') and the presence of a page URL per club, which the annotations do not convey. Return shape beyond that is left implicit.

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 the core action and scope, with no redundant restatement of the title or 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?

No output schema exists, and the description discloses the key return elements (clubs plus page URLs) and data vintage. Minor gaps: no note on ordering ties or what happens with an invalid slug, but nothing an agent needs 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?

With 0% schema description coverage, the description must carry the params, and it does: it gives the n bounds (1 to 20, default 10) matching the schema and specifies that league is a slug obtained from resolve. The 'undefined' fields are covered adequately without format examples.

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 top clubs of one league by 442ball Power Rating') plus the snapshot scope. The clause 'There is no list across leagues' and the pointer to resolve distinguish it from league-wide siblings like league_strength and greatest_sides.

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 resolve as the source of the league slug and rules out cross-league listing, giving real preconditions and one exclusion. It does not contrast against the closest siblings (club_rating, greatest_sides), which is why it falls 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.

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

Annotations already declare readOnly, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new behavioral detail: the month-end sampling rule, the 1-60 month window with a 24-month default, and that a club page URL is returned.

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?

A single dense sentence that front-loads the return value before the parameters, with no filler. It is slightly overstuffed with parentheticals, but nothing is wasted.

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 only two parameters, no output schema, and full annotation coverage, the description supplies the essential call-shaping facts (slug source, month window, sampling semantics, URL in response). It stops short of describing the fields in each monthly record, which an agent might still want.

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 must carry the load and largely does: 'club' is defined as the slug from resolve, and 'months' is bounded 1-60 with a stated default of 24. Only the slug pattern constraint and what format the returned series takes are left unstated.

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 ('Returns') on a specific resource ('442ball Power Rating month by month') scoped to one club, and clarifies the aggregation rule ('the last weekly value of each month'). An agent can distinguish this from the sibling 'club_rating' by the monthly time series framing.

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 prerequisite: the club slug must come from 'resolve', which prevents a whole class of failed calls. It does not state when to prefer this over 'club_rating' (current vs. historical), so the sibling routing is left implicit.

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=true, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds genuinely new behavior: a hard cap of five results and accent/case-insensitive matching, which affects how an agent should phrase retries. It stops short of saying what happens on zero matches, so not 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?

Three short sentences, each doing distinct work: purpose, workflow routing, input rules. The most important information (what it returns and that it should be called first) is front-loaded with zero 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?

Single-parameter tool with no output schema, and the description still discloses the result cardinality and per-result fields, plus matching behavior. There is nothing an agent needs in order to call this correctly that 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 0% — the schema only carries minLength/maxLength with no descriptions — so the description must compensate, and it does: '2 to 60 characters' restates the bounds usefully and 'accents and case are ignored' adds matching semantics found nowhere in the schema. It does not clarify whether multi-word or partial names are matched, keeping it below 5.

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 ('Finds clubs and leagues by name') plus the result shape ('up to five, each with its 442ball slug and page URL'). That return contract makes it clearly distinguishable from every sibling (club_rating, league_index, rankings), all of which consume the slug this tool produces.

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?

'Use it first when you have a name, then pass the slug to the other tools' gives an explicit ordering rule and names the downstream consumer, which is the whole sibling set. An agent knows both when to call this and what to do with the result.

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