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

Annotations cover the safety profile (readOnly, non-destructive), and the description adds substantial behavioral context beyond them: the subscription model, the 7-day trial, the x402 pay-per-call path, and the exact failure mode (PaymentRequired object with no data). This is exactly the gating information an agent needs before calling.

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?

Front-loaded with what the tool returns, then the live/subscription/payment mechanics. Four sentences, all earning their place, though the trial and connector-sign-in detail is slightly more than strictly necessary.

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 live, gated read tool with no output schema, the description covers the access model and fallback behavior adequately. It does not describe the shape of the returned ranking data, but the absence of an output schema makes that a minor gap.

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% and the single 'sector' parameter is documented as 'Sector name or sector-ETF symbol'. The description adds no format, casing, or symbol syntax detail beyond that, so the baseline 3 applies.

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: returns a sector's members scored and ranked from the current session. The phrase 'Live intraday version' distinguishes it from the non-live get_sector_read sibling without naming it explicitly, which keeps it just short of a 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?

Explains the access prerequisites clearly: subscription via Coil Live connector, or pay-per-call with an x402 wallet, otherwise a PaymentRequired object is returned. It implies use when live data is wanted, but does not explicitly route the agent to get_sector_read for non-live data.

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