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

Beyond the readOnlyHint=true annotation, the description discloses important behavioral details: each row represents one outcome token of one wallet, a wallet holding both sides appears twice, and Position PnL applies only to the displayed row. These pitfalls and row-scoping notes add real interpretive value that an agent could not infer from annotations or the schema.

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 well-organized with bold section headers, concise bullets for key fields, an explicit pitfalls section, and a one-line prerequisite. Every sentence adds non-obvious information and the most important framing comes first.

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 output schema exists, the description still explains the meaningful fields, warns about duplicate rows for two-sided positions, and routes to prediction_market_lookup when marketId is unknown. This is sufficient for an agent to know what the tool returns, what the numbers mean, and what to do before calling it.

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?

Although the reported schema description coverage is 0%, the nested schema itself documents marketId and page with meaningful descriptions. The tool description adds a useful prerequisite for obtaining marketId, but it does not explain the request wrapper or the pagination parameter, so it only partially compensates for the top-level schema 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?

The description opens with 'Detailed position breakdown for a Polymarket market,' which names a specific resource and the kind of output an agent can expect. It is clear and distinct from the many trading-history siblings, though it does not explicitly contrast itself with nearby tools like prediction_market_address_summary or prediction_market_trades.

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 gives a concrete prerequisite and an explicit alternative: 'If marketId is unknown, call prediction_market_lookup first.' It also implies the tool is for inspecting positions in a specific market, which gives an agent context for when to choose it, but it does not exhaustively list when-not-to-use cases against the other prediction_market_* tools.

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