TradeGauge

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: it discloses the return payload (verdict, value totals, consolidation/best-player/pick-heavy analysis) and that ambiguous or unknown names are reported back rather than silently failing. Minor gap: no note on which value source or how frequently values refresh.

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 paragraphs: the first front-loads the verb and the return contract, the second gives usage conditions and the name-passing rule. No redundancy with the schema and nothing that fails to earn its place.

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 evaluation tool with no output schema but full schema coverage on inputs, the description supplies what's missing: the shape of the result and how inputs are resolved. An agent has enough to select and call it correctly without further inference.

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 the schema already documents all six parameters, including the single-dynasty-table vs. redraft-split distinction on `format`. The description adds only one piece of semantic value—that side_a/side_b accept names as the user phrased them—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 (grade) and resource (dynasty or redraft trade) and enumerates the outputs: WIN/EVEN/LOSE verdict, per-side value totals, and structural context. This clearly separates it from sibling tools like get_player_value or get_rankings, which return raw values without a trade verdict.

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?

An explicit "USE WHEN" block names the exact user intents (is this fair, who wins, what evens it out) that select this tool over siblings. It also gives operational guidance to pass names as the user said them, with the tool handling resolution and ambiguity reporting.

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=true; the description reinforces this with 'Read-only: nothing is posted to Sleeper', which confirms no side effects on the external league. Beyond that it adds no behavioral detail such as the default trade limit, the fact that omitting week scans weeks 1-18, or how unrostered players are ranked.

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 lines: capability first, usage second, safety third. No filler, and the most important statement is front-loaded.

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 a call that returns two different things (completed trades and a ranked free-agent list), the description never indicates the shape or size of either result, nor that trade count is capped by the limit parameter. Adequate to select the tool, thin for interpreting what comes back.

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%, including the detailed dynasty-vs-redraft format explanation, so the schema carries all parameter meaning. The description adds nothing about week, limit, format, or league_id, which is acceptable at full coverage but no better than baseline.

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 (read completed trades from a Sleeper league) plus a second capability (identify highest-value unrostered players). Clear enough to distinguish from tradegauge_evaluate_trade and tradegauge_get_league_roster, though the dual-purpose nature (trades + free agents in one call) is only implicit.

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 'USE WHEN' line gives concrete triggering scenarios: what the league has paid, recent trade history, waiver targets, replacement-level context. It stops short of stating exclusions or naming the sibling tools to use instead for pure valuation 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 and openWorldHint, so the description sensibly spends its words elsewhere, adding the genuinely new facts that no login is needed and nothing is written to Sleeper. It does not cover rate limits or what an empty/unmatched league response looks like, which keeps it below 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 blocks, front-loaded with purpose then usage then a safety/flow note; every sentence carries information an agent would otherwise have to infer. No filler or repetition of the title.

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 names the returned fields and the auth posture, and all five optional params are covered by the schema. The one gap is behavior when neither `sleeper_username` nor `league_id` is supplied, since the schema marks nothing required.

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 the baseline is 3; the enum and per-param semantics are fully documented in the schema, including the dynasty-vs-redraft value caveat. The description contributes one workflow rule not in the schema (username-only first call, then league_id), which earns credit but doesn't push past baseline given the schema's completeness.

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?

Cites a specific verb pair ('pull real rosters' + 'price every team') and resource (a Sleeper league), and enumerates the outputs (total roster value, power ranking, best assets). It is distinguishable from player-level siblings by scope, but it never names `tradegauge_evaluate_trade` or `tradegauge_get_player_value` even though 'who should I trade' brushes against trade evaluation.

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 'USE WHEN' block gives concrete trigger phrases and, uniquely, prescribes a two-step call sequence: `sleeper_username` alone to list leagues, then `league_id`. What is missing is explicit routing away from the value/trade siblings, so an agent facing 'who should I trade' could still hesitate between this and `tradegauge_evaluate_trade`.

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 and openWorldHint, so the safety profile is covered. The description adds genuine behavioral context beyond that: the comparables are the practical answer to 'what could I get for him', and players inside the even band trade roughly one-for-one — a semantic the agent cannot infer from 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?

Two tight paragraphs: capability first, then a scannable 'USE WHEN' trigger with a clarifying sentence about the even band. No filler and the most decision-relevant content is front-loaded.

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 enumerates what is returned (value, ranks, tier, age, comparables) and what the comparables mean. It doesn't address the single required 'player' lookup flow or failure modes for an unknown name, a minor gap for a simple read 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% and the 'format' enum description already explains the single dynasty table vs. split redraft sets, so the schema carries this burden. The tool description adds nothing about parameters, which is acceptable at full coverage but not above baseline.

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 ('Full detail for a single player') and enumerates the returned dimensions: market value, overall and positional rank, tier, age, and comparables. The single-player framing distinguishes it from siblings like tradegauge_evaluate_trade (multi-asset) and tradegauge_get_rankings (list-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?

The 'USE WHEN' block gives explicit triggers: asking what one player is worth, or wanting trade targets at a comparable price. It stops short of naming alternative siblings or exclusions (e.g., 'use search_players to find the name first'), so it's clear but not fully 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?

readOnlyHint=true and openWorldHint=true already tell the agent this is a safe, externally sourced read, so the description needn't restate safety. It adds the notion that values are 'current market value' (i.e., live, shifting data), but says nothing about ordering of results, whether values are numeric or tiered, or how 'trade targets in a value range' is actually achieved given there is no range parameter — a notable loose end.

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 purpose sentence followed by a compact USE WHEN line; both are front-loaded and every clause carries information. No filler or restatement of the title.

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 ranking tool with no output schema, the description covers what it returns (top players ranked by current value) and how to narrow it. The remaining gap is that the return shape — rank, value, tier fields — and result ordering are never hinted at, and the 'value range' use case lacks a corresponding parameter.

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 enum values and defaults are fully documented in the schema. The description only mirrors the schema ('QB/RB/WR/TE, or PICK for rookie draft picks') without adding semantics such as how limit interacts with the position filter. 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?

States a specific verb and resource — 'Top players by current market value' — and scopes it as 'overall or filtered to one position', which is clearly distinct from the single-player focus of tradegauge_get_player_value and the movement focus of tradegauge_get_value_movers. It does not name any sibling explicitly, so it lands just short of a 5.

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 'USE WHEN' block gives concrete triggers ('rankings, tiers, who are the top dynasty WRs') and a secondary use case ('find trade targets in a value range'). It gives no explicit exclusions or negative routing (e.g., 'for one player use get_player_value'), so it is clear context without full 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 establish readOnly=true and openWorld=true. The description adds useful behavioral context by explaining that movement is measured against a recent market baseline rather than a fixed window, which affects interpretation. It does not cover output format, pagination, or data freshness beyond that, so a 4 is appropriate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, followed by explicit usage triggers and one useful caveat about the measurement baseline. Every sentence earns its place without repetition or 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, three-optional-parameter tool with no output schema, the description covers the core purpose, usage triggers, and metric semantics well. It could more explicitly describe return content, but it does note that players, direction, and move size are returned, making it largely complete.

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 all three parameters are fully documented in the schema. The description only implicitly touches direction via 'risers and fallers' and does not add syntax or format detail beyond the schema. Baseline 3 is correct 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 states a specific resource and scope: players whose dynasty market value has moved recently, including risers/fallers and move size. This clearly distinguishes the tool from generic player value or rankings siblings by focusing on recent market movement. It does not explicitly name sibling tools as alternatives, so it falls short of a 5.

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 'USE WHEN' line gives concrete triggers: trending up/down, buy-low/sell-high candidates, or market changes. It provides clear usage context but does not state when not to use it or explicitly route to alternative sibling tools.

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?

readOnlyHint and openWorldHint already declare the safety and reach profile, so the bar is lower. The description adds genuinely useful behavior — ambiguous names return several candidates rather than one — but says nothing about value units, data freshness, or empty-result 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-loads the verb and return payload in one sentence, then a compact usage block. No filler, and the ambiguity warning earns its place.

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 names the returned fields (value, positional rank, tier) and explains multi-candidate responses, which is what an agent needs to consume results. Minor gaps like value units or empty-result handling keep it from 5.

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 'format' parameter is already documented in detail in the schema, including the one-dynasty-table caveat. The description itself adds no parameter meaning, 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 — find players (and rookie picks) by name — plus what it returns: market value, positional rank, tier. That distinguishes it from the value/ranking siblings, though it never names those siblings 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?

A dedicated 'USE WHEN' line gives clear triggering context (resolving a name before grading a trade, answering 'what is X worth') and warns that ambiguous names return multiple candidates that must be disambiguated. It lacks an explicit 'use get_player_value instead when you already have an ID' exclusion, so it stops just short of 5.

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