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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely new context beyond them: "Free, no key" (no authentication required) and the returned decision read (BUY/SELL/SKIP). The closing track-record sentence is promotional rather than behavioral, and no rate-limit or failure behavior is described.

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 sentences front-load the trigger phrase and the input/output contract with no wasted words. The final marketing sentence about the public track record does not earn its place in a tool definition.

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?

An output schema exists, so return values need no elaboration, and the two fully documented parameters plus annotations cover most of the surface. The one nuance it raises but does not resolve is that both parameters are technically optional while being "Required for a real answer" — it never says what degraded result appears if either is omitted.

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% and both parameters already document the accepted formats (55, "55%", "$0.55", 0.55, American odds), so the baseline is 3. The description only restates that inputs are a price in cents and your own probability, adding no format or constraint detail beyond the 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 names a concrete operation (compute the % expected-value edge from a contract price and your probability) and states the output shape (edge plus BUY/SELL/SKIP). Naming Kalshi/Polymarket pricing implicitly separates it from commodity_edge and the perps tools, but it never explicitly differentiates from the closely related kelly_size or convert_probability siblings.

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?

"Use for 'is this contract mispriced' and 'what is my edge'" gives a clear triggering intent and a concrete input recipe (price in cents + your probability). It does not name alternatives or state when NOT to use it — e.g. that kelly_size is the follow-up for sizing a bet — so routing between siblings is left to inference.

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