polymarket_get_positions

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

With no annotations, the description carries the full burden. It discloses the data source ('Polymarket Data API'), the scope ('configured wallet'), and return contents (P&L, flags, market info). However, it does not explicitly state that this is a read-only operation, nor does it mention authentication requirements, rate limits, error behavior, or side effects. The response field list adds transparency about output but not about underlying behavior.

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 structured with an introductory purpose sentence, a parameters section, and a response includes section. It is not overly verbose, though listing response fields adds length. The front-loaded purpose and clear sectioning make it easy to scan, and every part serves a purpose given the lack of an output schema.

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 there is no output schema and no annotations, the description provides a thorough overview: purpose, parameter semantics, and detailed response fields. It misses some operational context like error handling, rate limits, or authentication specifics, but for a simple read-only position lookup, it covers the essential information adequately.

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 description explains all three parameters beyond the schema: redeemable ('Filter to only show redeemable (resolved) positions'), market ('Filter by condition ID'), and limit ('Max results 1-500, default 100'). This fully compensates for the 0% schema coverage and does not merely repeat schema constraints—it adds meaningful semantics.

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 clearly states the tool's purpose: 'Get real positions (token holdings) for the configured wallet from Polymarket Data API.' It distinguishes from siblings by emphasizing 'actual token balances with P&L, not just open orders,' contrasting with order-related tools. The verb-resource pair is specific and unambiguous.

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 provides clear context for when to use this tool: when you need actual token holdings with P&L for the configured wallet. It indirectly differentiates from open-order tools but does not explicitly name alternatives or state exclusion criteria. The 'not just open orders' phrasing implies a contrast with order-related sibling tools, but explicit guidance is missing.

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