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

No annotations are provided, so the description carries the burden. It discloses the paid nature, cost, and authentication requirements (X-API-KEY or x402), and mentions that uncredentialed calls return a 402 payment envelope. However, it doesn't describe what happens on success (return format) or any rate limits, which are important for a paid API.

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 a single dense paragraph that packs a lot of information: the tool's purpose, the sport parameter, and payment details. It's front-loaded with the core purpose, but the payment and authentication details are lengthy and could be separated for clarity. It's not overly verbose, but the structure could be improved.

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 (paid access, multiple sports, authentication), the description covers the essential operational details: cost, payment method, and required parameter. However, it lacks information about the output format, success behavior, and any rate limits or quotas, which are important for a paid API. The pointer to the 'instruments' tool for parameter docs is helpful but incomplete.

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?

The input schema has zero parameters and a generic additionalProperties string, with schema description coverage at 100% (though it's just a pointer to the 'instruments' tool). The description compensates by listing the required sport parameter and its possible values (soccer, mlb, nfl, etc.), which is essential for invocation. It also mentions the ?sport= query parameter format, adding practical usage detail.

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 scans Polymarket per-sport moneyline markets against de-vigged sportsbook consensus, and lists supported sports. It distinguishes from siblings like signal_sports and signal_polymarket by specifying the per-sport moneyline focus and the required sport parameter, though it doesn't explicitly name alternatives.

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 explicit usage context: it requires a sport parameter, mentions season-aware soccer, and explains the paid access model with cost and authentication requirements. It doesn't explicitly state when not to use it or name alternative tools, but the context is clear enough for an agent to decide.

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