Retained price changes for an event or offer

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

Beyond readOnlyHint and openWorldHint, the description discloses genuinely useful behavior: the data is retained rather than complete, it only contains changes that GetOdds captured, and it is sourced from a specific provider. That coverage caveat is exactly the kind of limitation an agent needs before treating the result as a full price timeline. It does not address ordering, time bounds, or result size, which keeps it from 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?

Two short sentences, both load-bearing: the first defines the resource and scope, the second immediately qualifies completeness. The caveat is front-loaded rather than buried, and there is no restatement of the title or name.

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 and no annotation explaining returns, so the description must carry the semantic load, and it does explain what the returned records represent. It is silent on pagination behavior for limit, on what the market filter does to the history, and on whether the two identifiers conflict. Adequate to call the tool, not complete for using it well.

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 four parameters lean heavily on the description — and it only clarifies that event_id and offer_id identify a single subject for the query. The mutual-exclusivity intent is inferable from 'one event_id or offer_id', which is real added meaning, but limit and market receive no mention at all, leaving half the surface undocumented.

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 resource — retained price changes — scoped to one event_id or offer_id, and attributes the source (DraftKings via ESPN). An agent can tell this apart from a current-odds fetch because the description frames it as a change history rather than a snapshot. It stops short of naming a sibling, but the resource itself is unmistakable.

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 implied by 'for one event_id or offer_id' — an agent knows it must supply one identifier of that kind — but there is no explicit when-to-use versus get_odds or get_odds_board, and no statement about when a caller should prefer current odds instead. The 'not a complete tick history' caveat hints at a fitness-for-purpose boundary without fully stating it.

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