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

The description goes far beyond the readOnly/idempotent annotations, disclosing detailed behavioral nuances: parallel fan-out, resolver confidence levels, low-confidence short-circuit behavior, closed-market handling, wide-spread market warnings, and cancellation-rule parsing. It even explains the practical reality of de-indexed markets and the blocking nature of both routes. This is comprehensive and adds substantial value beyond annotations.

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 long but extremely well-structured with clear section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, SAFETY, etc.) and a front-loaded purpose statement. Every section adds necessary detail for a complex tool, so it earns its place. However, the sheer volume of information and some redundant clarifications (e.g., explaining both blocking routes repeatedly) prevent a perfect 5.

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 high complexity and the absence of an output schema, this description is exceptionally complete. It covers input formats, classifier types, fan-out examples, response shapes (market, analysis, evidence), resolver contract, parent-event extraction, news fallback fields, safety behaviors, and cancellation-rule risk. It leaves little to guesswork, making it a fully self-contained reference for an AI agent.

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 already provides 100% descriptive coverage of all three parameters, so the baseline is 3. The description enriches this by giving concrete fan-out examples that illustrate what 'thorough' depth produces per market category, and by explaining the input format (slug/URL/question) in the context of the resolver. It does not explicitly discuss depth/include_raw by name, but the examples and response-shape explanations add meaningful context 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 first sentence clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It uses a specific verb ('research') and resource ('Polymarket bet') and distinguishes itself from siblings by focusing on market-vs-model comparison and evidence packets for betting decisions. The 'Use for' section further clarifies its niche.

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 explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides extensive fan-out examples for different bet categories, giving concrete context. However, it does not explicitly mention when not to use it or compare it to alternatives like search or validation tools, so it falls short of a 5.

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