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

Beyond readOnlyHint it discloses behavior the annotation cannot: it aggregates matching active saved accounts, returns per-account partial failures without discarding successful holdings, includes accountDisplay on every successful account/position/failure, and never returns full account numbers. It also warns never to pass raw broker credentials and notes includeCashPositions defaults to false.

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 routing constraint is correctly front-loaded, but the description runs roughly 250 words for a five-parameter read tool, and a large trailing block is presentation policy (pie/donut vs bar charts, gain-loss bars, Markdown tables, BotSpot card visibility) that does not help an agent choose or invoke the tool. That bulk dilutes the genuinely useful selection signal.

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 read-only tool with no output schema, the description covers what matters: aggregation scope, partial-failure semantics, the accountDisplay field, credential safety, and default behavior of includeCashPositions. The only real hole is the undocumented assetType enum parameter.

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?

With 0% schema description coverage the description must carry the load, and it does for four of five parameters: brokerCredentialId (only when the user explicitly identifies one saved account), brokerProvider (exact value from list_broker_credentials, omit for all accounts), symbol (narrow to one asset), includeCashPositions (defaults to false). assetType is never mentioned, so one parameter remains undefined in both schema and description.

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 opening sentence states a specific verb and resource ('fetches current positions directly from saved broker credentials') and immediately negates the two nearest confusions, deployment telemetry and snapshot automation. An agent can distinguish it from get_deployment_position_telemetry, broker_snapshots, show_holdings and show_bot_activity without opening any 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?

It names the alternatives and the exact condition selecting each: show_bot_activity first for named-bot performance, this tool only after a failed or stale read and explicitly not as a preflight; show_holdings first for general allocation questions; this raw reader for specifically requested raw details. It also states the argument pattern per scenario (omit brokerCredentialId and pass brokerProvider for one provider, omit both for all accounts).

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