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

Adds substantial context beyond the readOnlyHint/destructiveHint annotations: per-broker segmentation, paper vs live separation, the snapshot-based chart, the conditional allocation donut (only when holdings are complete), reconnect links for expired credentials, and the MCP Apps panel versus text-summary fallback. These are exactly the caveats an agent needs to interpret results.

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-loads the user question and the returned fields, then adds short sentences for edge cases and rendering modes. Slightly dense in the opening sentence and the "Read-only" clause duplicates the annotation, but there is no filler.

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, and the description fully covers what comes back, including degraded cases (reconnect link) and conditional sections. The only real hole is parameter guidance, which for a 2-param, enum-bearing tool is a notable but not fatal omission.

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 carry the parameter burden, and it does not. Neither `mode` (live/paper/all) nor `brokerCredentialId` is mentioned; the sentence "Paper and live accounts are shown separately" describes output, not the filter, and gives no hint that a scoping parameter exists.

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 (account overview) and enumerates exactly what it returns: account value, cash, unrealized P&L, position count per broker account, a history chart from saved daily snapshots, and an allocation donut. That scope cleanly separates it from per-position siblings like show_holdings and from series/detail siblings like get_portfolio_series or get_broker_account_snapshot.

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 framing question "How is my account doing?" implies when to reach for this tool, but it never names an alternative or exclusion. With close siblings such as get_account_status, show_holdings, broker_snapshots, and get_portfolio_series present, an agent must infer the boundary itself.

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