Automaton Polymarket Analytics (unofficial)

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

With no annotations, the description carries the full behavioral burden, and it does disclose two real constraints: the candidate universe is capped at the 500 most-traded active markets, and markets past their end date are excluded. It does not state sort order, whether results are paginated, or that this is a read-only listing.

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 short sentences, front-loaded with the core purpose and followed by the one exclusion rule that matters. No filler and nothing redundant.

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?

For a four-parameter tool with no annotations, no output schema, and 0% schema description coverage, the description leaves too much unspecified: result ordering, the direction enum's effect, the limit cap of 50, and how min_volume_24h interacts with the '500 most-traded' universe.

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 0%, so the description must compensate for all four parameters. It explains only the window values ('1h, 1d or 1w'); limit, direction, and especially min_volume_24h (default 10000) are never addressed, and the volume filter is not even implied by the '500 most-traded' phrasing.

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 specific resource and scope: 'Biggest price moves among the 500 most-traded active Polymarket markets.' That is concrete enough to separate it from top_markets (volume ranking) and market_snapshot (single market state), though it never names a sibling explicitly.

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?

There is no when-to-use guidance and no mention of alternatives among the five sibling tools. The window universe ('500 most-traded') and the expiry exclusion hint at scope, but an agent is left to infer when this tool is the right pick over top_markets or search_markets.

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

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

With no annotations and no output schema, the description carries the burden, and it does so well by enumerating the returned payload: outcomes/prices, bid/ask/spread, volume, liquidity, CLOB midpoint, 24h high/low/change, and a summary line. It still omits read-only affirmation and error behavior for invalid ids, which is why it isn't a 5.

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?

A single front-loaded sentence that names the resource first and then lists return contents after a colon. Every element earns its place; no filler or repetition.

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?

For a one-parameter read tool with no output schema and no annotations, the return-content inventory makes the definition largely self-sufficient. Minor gaps remain around failure modes and freshness of the quoted prices.

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% and the schema already documents 'Market id (numeric) or slug'; the description repeats rather than extends that. Baseline 3 applies since the schema does the work and the description adds no format, validation, or ambiguity guidance.

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?

States a specific verb and resource ('Details for one Polymarket market'), plus the exact lookup key ('numeric id or slug'). The singular, identifier-driven framing cleanly separates it from the list-oriented siblings (search_markets, top_markets, biggest_movers).

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?

Usage is only implied: the agent can infer 'use when you already have a market id/slug and want detail.' No alternative is named and no when-not condition is given, so it falls short of the explicit routing seen in stronger definitions.

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

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

With no annotations, the description carries the full behavioral burden. It partially meets it by disclosing what the digest is composed of and that alerts are threshold-driven, which tells the agent this is a composite read. It says nothing about rate limits, freshness/caching, cost of the call, or whether any filters reorder or suppress digest sections.

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?

A single sentence that front-loads the core purpose and then lists the four digest sections in order. No redundancy; 'built for agents' is the only phrase of marginal value, but it is not enough to undermine an otherwise tight structure.

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?

For a zero-annotation, no-output-schema tool, the description usefully conveys the return shape by enumerating the four sections, which is the right move. It still leaves gaps: the role of each numeric parameter, the ordering/truncation behavior of the list, and the fact that the 48h window is fixed rather than configurable.

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 only 33%: alert_pp is documented in the schema, while limit and min_volume_24h have no description at all. The description partially compensates by tying '1-hour move alerts above a threshold' to alert_pp and 'top markets by 24h volume' to the volume filter, but it never explains what limit bounds or how min_volume_24h interacts with the mover/alert sections.

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?

Names a specific resource (Polymarket market digest) and enumerates the exact contents: 24h-volume leaders, 1-day movers, 1h move alerts, and liquid markets ending within 48h. This is clearly distinguishable from a single-market tool, but it never explicitly positions itself against the overlapping siblings top_markets and biggest_movers, whose data it apparently bundles.

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 framing 'compact digest... built for agents' implies a use case (a one-call overview rather than a targeted lookup), and the 48h/alert contents hint at a monitoring scenario. However, there is no explicit when-to-use statement and no exclusion or routing guidance relative to top_markets, biggest_movers, or search_markets.

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

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

With no annotations, the description carries the full behavioral burden, and it does disclose the core behavior in detail: the comparison scope and the exact conditions that produce a flag (YES prices/asks/bids not summing to ~1, ladder ordering violations). It leaves gaps on read-only/safety status, data freshness, and the shape of the flags it emits, but the analytical semantics are unusually well exposed.

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?

A single front-loaded sentence: verb and scope come first, and the colon-plus-examples clarify the detection rules without padding. It is dense and slightly run-on, but every clause (the mutually-exclusive, threshold-ladder, and date-ladder cases) earns its place.

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?

For a read/analysis tool with no output schema and no annotations, the description is complete enough on what it computes and what a flag means. It could say more about the returned structure (e.g. which markets and inconsistencies are listed) and its read-only nature, but nothing critical to invoking it correctly is missing.

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 params are documented in the schema (market id/slug with parent event analysed, or an event id/slug). The description only echoes this by noting it accepts "a market (or an event)", adding no format or precedence detail, so the 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?

States a precise verb ("Compare") and resource ("all open markets in the same Polymarket event") and spells out the exact analytical output (flagging mutually-exclusive sums off ~1, out-of-order threshold/date ladders). This cross-market scope inherently separates it from single-market siblings like get_market and market_snapshot, so an agent can route correctly without opening either schema.

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 trigger is clear: you call it with a market or event id when you want to detect inconsistent pricing across an event's markets. It doesn't explicitly name alternatives or state when not to use it (e.g. for a single market, use market_snapshot), so it stops short of full when/when-not guidance.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses a scope constraint — only active events and open markets are searched, so closed/archived items won't appear — but says nothing about result ordering, return shape, or rate limits.

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?

A single tight sentence with the resource and search mechanism front-loaded and zero filler. It is efficient, though its brevity contributes to the gaps noted elsewhere.

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?

For a simple two-parameter search tool with no output schema and no annotations, the description covers the core intent but omits what a result looks like (events vs. markets nesting) and how limit interacts with results. Adequate, but not complete.

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 50%: q is documented in the schema with examples, while limit (default 5, max 20, min 1) has no description. The phrase 'by keyword' adds only marginal clarification over the schema's own example text, so the description does not fully compensate for the gap.

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?

Specific verb (search) + resource (active Polymarket events and their open markets) + mechanism (by keyword). It is distinguishable from siblings like get_market and top_markets, though it never names them explicitly.

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?

Usage is only implied by 'by keyword' — the description never states when to prefer this over get_market (a specific market), related_markets, or top_markets. No exclusions, prerequisites, or routing guidance are given.

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

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

With no annotations, the description carries the full burden. It does disclose two useful traits: only 'active' markets are returned, and volume24hr is the default ranking. It says nothing about pagination, result size limits, refresh/rate behavior, or whether the ranking is live.

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?

A single dense sentence with the core purpose and the default ranking front-loaded. No filler, though the trailing enumeration of return fields is slightly list-like and the phrasing 'or all-time volume' is a touch compressed.

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?

With no output schema and no annotations, the description usefully enumerates returned fields (prices, bid/ask, spread, price changes, volume, liquidity) and the default sort. Missing only limit/pagination behavior, which is minor for a two-parameter read tool.

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 0%, so the description must compensate. It does explain the 'by' dimension in plain language matching the enum values (24h volume, liquidity, all-time volume) and flags the default. It entirely omits the 'limit' parameter and its 1-50 range, leaving one of two parameters undocumented.

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?

Names a specific resource (active Polymarket markets) and the ranking dimensions (24h volume default, liquidity, all-time volume), plus the data returned. An agent immediately knows this is a ranked market listing. It does not, however, differentiate itself from the sibling biggest_movers, which also ranks 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?

No explicit when-to-use or when-not-to-use guidance. The default sort is stated, but nothing tells the agent when to pick this over biggest_movers, search_markets, or market_snapshot. Usage must be inferred from the name and description.

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