Search Polymarket markets

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

No annotations are provided, so this description carries the behavioral-disclosure burden. It does that reasonably well by explaining that resolved markets are excluded by default, that include_closed flips that behavior, and that coverage is limited to Polymarket crypto markets. It stops short on return-shape/pagination expectations, but the important filtering defaults are clearly stated.

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 five sentences are information-dense without being padded: purpose, first-step rationale, scope, closed-market default, and sibling alternative each contribute distinct meaning. The introduction is a bit of run-on phrasing, but there is no fluff.

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?

The description supplies the essential context an agent needs to choose and use the tool, especially the entry-point position and the default exclusion of resolved markets. However, there is no output schema or explicit statement about what the result shape contains, ordering, or whether pagination matters, so the agent has to infer something important about how to consume the 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?

The schema already covers all five parameters with useful descriptions, including call behavior. The tool description mainly paraphrases that behavior (include_closed/historical analysis) rather than adding new semantics. Since schema coverage is 100%, a baseline of 3 is appropriate.

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?

Opens with a specific verb and resource: 'Find Polymarket markets by keyword.' It clarifies coverage (crypto up/down and threshold contracts) and differentiates itself from slug-dependent sibling tools by explicitly warning that slugs are not guessable and that search_series is better for a family of markets.

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 says to 'start here' and explains why: other tools need a market slug, and this tool is the way to obtain it. It also names search_series as an alternative for whole market families and explains that historical work should pass include_closed everything.

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