tab_trending_props

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, so the safety profile is covered without description help. The description adds genuinely useful behavioral context beyond annotations: the return shape ('top-level array' with a partial field list) and the auth behavior ('works without a key; ... unlocks more if set'). However, it stops short of richer disclosure such as the trending time window, result count, or what specifically 'unlocks more' means.

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 compact and well-organized: a one-line functional statement, then a Returns line, then an Auth line. Each section earns its place, and the primary purpose is front-loaded. Minor inefficiency — the vague 'unlocks more' clause — costs a point but overall structure is tight.

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-optional-parameter, read-only tool this is mostly adequate: the description covers purpose, partial return shape, and auth prerequisites, and annotations cover safety. Gaps remain: there is no output schema and the '...' in the return sample leaves the full field set underspecified, the trending time window is unstated, and the jurisdiction param's accepted values are not elaborated. These are open questions an agent would hit when interpreting results.

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% (the sole parameter 'jurisdiction' has 'State jurisdiction.' plus a default of 'NSW'), so per baseline the schema carries the load. The description adds nothing about the parameter beyond the schema, and the schema's 'State jurisdiction.' is minimal — it doesn't enumerate valid states or clarify that these are Australian jurisdictions.

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 ('sports propositions / bets') and scope ('across the book'), which conveys a book-wide trending view rather than a match-specific one. It is clear enough to distinguish from match-level tools like tab_match_markets or tab_price_slip. However, it doesn't explicitly differentiate itself from sibling trending tools like sportsbet_trending_sgm or tab_recommendation_featured.

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 context is implied rather than stated: 'trending ... across the book' signals this is a discovery/overview tool, and the optional jurisdiction parameter hints at geographic scoping. But there is no explicit when-to-use or when-not-to-use guidance, and no alternative tool is named for cases where a narrower query (e.g. specific match, race, or SGM) would be apt.

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