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

The readOnlyHint annotation already covers the safety profile, so the description isn't burdened with saying this is a safe read. It adds useful behavioral context: the data are recorded snapshots, not live broker valuations, and it documents the lookback window defaults and maximum. It does not describe snapshot cadence, ordering, or error behavior, but with annotations present this is a solid addition.

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?

Three sentences with no waste. The return content is front-loaded, the lookback parameter is explained in the middle, and the sibling guidance/caveat closes the description.

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 lists the key return fields and explains the only non-obvious parameter and the refresh caveat. It does not mention snapshot interval or ordering, but for a read-only metrics tool with annotations covering safety, it is nearly complete.

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 must compensate. It does so well for hoursAgo, giving the default (168 = 1 week) and max (720 = 30 days), which the schema alone does not explain. deploymentId is not explicitly defined, but its UUID format is in the schema and the name is self-explanatory.

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 names a specific verb and resource ('Returns recorded performance snapshots for a live deployment's bot') and enumerates the metrics included (total return, max drawdown, Sharpe ratio, portfolio value over time). It is clearly distinguishable from sibling tools such as show_bot_activity and get_portfolio_series.

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?

It explicitly names an alternative, 'use show_bot_activity first', for current account performance, and adds a clear exclusion: this telemetry does not refresh broker valuations. That gives the agent an actionable routing rule and a caveat about what this tool will not provide.

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