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

Annotations already cover read-only, idempotent, and non-destructive behavior, but no side-effect description is needed. The description adds genuinely useful behavioral context: venue=None changes aggregation, detail changes the returned fields, and position_id is chained into close_perp_position. This exceeds what the annotations and schema alone tell the agent.

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 compact and front-loads the operation before explaining optional behaviors. It avoids unnecessary filler while still explaining the important differences in venue and detail modes. A tiny bit more structure, such as labeling parameters explicitly, would make it fully polished.

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 rich annotations and the presence of an output schema, the description covers the necessary usage semantics for a safe, read-only tool. It tells the agent how venue=None behaves, how detail controls output, and why position_id matters for downstream action. It does not mention caller_id, but that is optional and secondary.

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 carries the parameter documentation burden. It explains venue aggregation and detail modes in useful detail, including exactly which fields each detail level includes. It does not explain caller_id, which is an optional parameter, but the other parameters are meaningfully enriched beyond the raw schema.

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 identifies the resource as open perpetual positions for a wallet and explains the all-venues aggregation behavior. It is slightly ambiguous whether 'Open' is a verb or an adjective, but the read-only annotations and the focus on position details make the intent recoverable. It does not explicitly contrast with sibling perp_positions, so it stops short of a perfect 5.

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 implies when to use the tool: venue=None aggregates across venues, which suggests this is for multi-venue position retrieval. However, it never explicitly states when to prefer this over a tool like perp_positions or how to limit to a single venue. There are no exclusions or named alternatives, so guidance is only implicit.

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