parlayapi_find_middles

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

No annotations are preset, so the description carries the full burden of explaining behavior. It clearly states that the tool scans available markets and returns windows, hitting numbers, and per-$100 economics, which makes the purely informational/report-like behavior transparent. It does not mention auth or rate limits, but nothing about the description implies harmful side effects.

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 thorough but every sentence earns its place. The definition, illustrative example, coverage scope, output economis, and parameter documentation are organized and front-loaded, making it easy for an agent to quickly understand and invoke the tool.

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 tool's complexity, the description fully covers inputs, optional defaults, scope of search, and the economics of the return. The output schema handles specific return-field expectations, and the description provides the tactical context an agent needs to call this tool correctly and interpret its 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 0%, so the arguments section is the sole source of parameter meaning. It explains all four parameters: sport_key with examples, min_gap as window width, market s a comma-separated optional filter, and include_props as a boolean toggle. This adds substantial value beyond the raw schema.

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 action ('Find cross-book middle opportunities') and thoroughly defines what a middle is with a concrete example. It calls out the scanned markets (totals, spreads, player props), which clearly distinguishes it from sibling tools like parlayapi_find_arbitrage and parlayapi_find_ev.

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 provides clear execution context by specifying sport_key requirement, market filtering, and prop inclusion, and it names the kinds of outcomes returned. It does not explicitly contrast itself with find_arbitrage or find_ev, but the intended use is easy to infer from the detailed middle-explanation.

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