List Perps instruments

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered for free. The description adds genuinely non-structured behavior: this list is the authoritative source of instrument_id used by all other Perps tools. The field enumeration is largely redundant with the existing output schema, which keeps it from a 5.

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?

Two sentences, zero filler. The resource and its contents come first, and the cross-tool dependency — the single most decision-relevant fact — is front-loaded as the closing sentence rather than buried.

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?

For a simple read-only list tool with a full output schema, the description covers purpose, contents and downstream use adequately; return-value detail is rightly left to the output schema. The gap is that `category` and `include_risk_tiers` go unexplained, which matters slightly for an agent trying to narrow a large market list.

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 50%: `search` (symbol substring, e.g. BTC) and `instrument_id` (including a settled one) are already documented in the schema, and the description only restates them indirectly. The `category` filter and `include_risk_tiers` flag are not explained at all — the mention of 'notional limits' hints that risk tiers relate to limits but never says what enabling it does. Baseline 3 for partial coverage.

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 (list perpetual markets) and enumerates what each entry carries: id, symbol, category, decimals, leverage, notional limits, funding interval. It also distinguishes itself from every sibling tool by declaring that 'every other Perps tool takes the integer instrument_id from here', so an agent can tell this is the ID-resolution entry point rather than a market-data or order tool.

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 sentence about other Perps tools consuming instrument_id clearly implies the intended call order: use this first to resolve an ID, then call the target tool. It does not give explicit exclusions (e.g. 'use get_perps_tickers for price data'), so it falls short of a full when/when-not treatment, but the context is unambiguous.

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