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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so safety is covered; the description adds real value beyond that by explaining row granularity (one outcome token per wallet) and by scoping Position PnL to the displayed row rather than wallet totals. It does not describe pagination behavior or result-set size, which is the main behavioral gap.

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?

Front-loaded purpose sentence followed by scannable Key fields and Pitfalls sections; each field note explains a non-obvious accounting distinction rather than restating the field name. Minor redundancy with the output schema and a slightly heavy bullet list keep it from a 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?

With an output schema present, the description need not explain return format, yet it goes further by interpreting the trickiest fields and warning about duplicate wallets. The remaining gaps are pagination semantics and explicit sibling routing; note also that the description says to use prediction_market_lookup for marketId while the schema description points to prediction_market_screener, a minor inconsistency an agent must reconcile.

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 the nested request object documents both marketId and page with constraints, so the schema carries the load. The description repeats the marketId sourcing hint but adds no semantics for the page parameter or result ordering, so the baseline 3 applies.

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: a detailed position breakdown for a Polymarket market, with field-level semantics for position size, cost, proceeds, unrealized/redemption value and PnL. It implicitly separates itself from sibling tools like prediction_market_address_pnl by noting each row is one outcome token of one wallet, but it never explicitly names the sibling it is not, leaving the market-wide vs per-wallet distinction to be inferred.

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?

Gives an explicit prerequisite rule — call prediction_market_lookup first if marketId is unknown — and a usage pitfall about wallets holding both outcome sides appearing twice. It offers no guidance, however, on when to prefer this over related siblings such as prediction_market_address_pnl, prediction_market_top_holders, or prediction_market_address_summary.

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