Recent-Tier Cohort Top Positions

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

Annotations already cover readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds behavioral context beyond those annotations by disclosing that the result is restricted to 'currently-printing wallets' and by enumerating the returned fields (entry/exit VWAP, hold duration, realized PnL, fees, liquidation flag). This helps the agent understand the data contents without an output 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 a single dense sentence that front-loads the core object ('Top closed position lifecycles') and then efficiently packs the cohort definition and output fields. It is not padded, but the sentence is long and somewhat run-on, requiring careful parsing. Still, every phrase contributes meaningful information.

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, the description does a good job listing return fields and explaining the cohort. However, it leaves ambiguity about the time range of the positions themselves (only the tier is defined by last-30-days) and what criteria define 'biggest/most notable'. These gaps could lead to incorrect invocation or interpretation, though the schema covers pagination and format parameters.

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%, so the schema already documents each parameter thoroughly. The description does not add parameter-specific meaning, such as explaining how tierType or tier interact with the cohort definition. It provides high-level context about the cohort but does not go beyond the schema, hence the baseline score.

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: 'Top closed position lifecycles' and the specific cohort definition: 'a cohort defined by its LAST-30-DAY tier' from 'currently-printing wallets'. It lists concrete output metrics (entry/exit VWAP, hold duration, realized PnL, fees, liquidation flag), making the tool's purpose specific and distinguishable from siblings like pulse_cohort_recent_positions or pulse_cohort_recent_trades, even without naming them.

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—when you need top closed position lifecycles for a recent-tier cohort—but it does not explicitly state when not to use it or name any alternative sibling tools. No exclusions or comparisons are provided, so an agent must infer the appropriate context from the description alone.

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