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

Beyond the annotations (readOnly, idempotent), the description extensively discloses behavior: resolution process, fan-out patterns, response shapes, edge cases (low-confidence short-circuit, closed markets, illiquid spreads), and rule-risk analysis. It even explains the resolver contract and parent-event extractor. No contradictions with annotations; the description greatly enriches the agent's understanding.

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?

While the description is long, it is extremely well-structured with clear headings (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, etc.) and every sentence adds necessary information. There is no redundancy. The length is appropriate for the tool's complexity, and the structure makes it easy for an AI agent to parse.

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?

Despite lacking an output schema, the description thoroughly covers all critical aspects: market resolution, classifier selection, evidence sources, response fields, safety mechanisms, and rule-risk. It addresses potential pitfalls (low-confidence matches, closed markets, wide spreads) and provides actionable guidance. The tool's complexity is fully addressed.

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 baseline is 3. The description adds value for the market parameter by specifying three valid formats (slug, URL, question text). For depth and include_raw, the description does not add beyond the schema's documented defaults and behavior, but the extra context for market justifies a point above baseline.

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 opens with a clear verb+resource statement: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on general research and data retrieval. Additional context about classifiers and response shapes reinforces the tool's specific role.

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?

Explicit use cases are provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' The description also gives detailed guidance on when to inspect market_match_confidence, parent_event fields, and cancellation rules, effectively telling the agent when to trust results and when to be cautious. This covers both usage and exclusion.

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