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

Annotations already cover read-only/idempotent/open-world, so the bar is lower, yet the description goes well beyond them: it discloses that all figures are gross of taker fees, basis moves, and two margin accounts, that realized_7d_* goes negative when the spread reverses, and how mark_gap_bps sign should be read. These are exactly the caveats that change how an agent reports a result.

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 the key qualifier ("REALIZED numbers, out of sample") and every clause defines a named output field or a caveat, so little is wasted. The single dense run-on with nested parentheticals makes it harder to scan than it needs to be, and the field definitions could be broken out.

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?

There is no output schema, so the description takes on the job of defining the returned columns and does so for every field it names (realized_7d_*, positive_share_7d, current_spread_apr, mark_gap_bps), plus the gross-of-cost caveat. Nothing an agent needs to interpret or caveat the results is absent.

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 both parameters (limit, min_venues) are documented inline, so the schema carries the parameter burden. The description adds no syntax or tuning guidance for min_venues or limit, meaning it neither compensates nor detracts; 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 ("Funding carry screener on REALIZED numbers, out of sample") and immediately defines the constructed object: the venue pair a desk would have put on a week ago versus what it earned over 7d/30d. It explicitly distinguishes itself from get_funding_dispersion, so an agent can tell the two apart without opening either schema.

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?

Names the alternative and the condition that selects it: "Use get_funding_dispersion for the live spread across all venues," positioning this tool as the realized/backward-looking counterpart. What is missing is a direct when-to-use clause for this side of the split (e.g. "use this to evaluate whether a carry pair would have paid"), though the framing strongly implies it.

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