cricket_find_value_bets

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent and description adds critical context: empty results, neutral baseline, events_analysed count, and reasoning. No contradiction.

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 well-structured with a clear purpose, note, args, and returns. It is front-loaded and concise for the complexity, though slightly verbose with the NOTE section.

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?

Given the output schema exists, the description explains the empty list, events_analysed, model, and note. It covers all relevant behaviors and meta information, making it fully 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 the description's parameter info is largely redundant. However, it adds context for min_edge ('Currently informational only'), which adds some value beyond schema descriptions.

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 clearly states the tool 'Compare model probabilities against market-implied IPL odds' with a specific verb and resource. It distinguishes from siblings like cricket_get_live_odds and mentions a required key.

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 notes the current limitation (empty list until model is wired) and provides an alternative: 'For raw de-vigged prices use cricket_get_live_odds'. Also explains behavior for filtering with team and min_edge.

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