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

Annotations only cover read-only safety, and the description adds substantial behavioral context: balances and holdings come directly from the exact linked broker with source/retrieval timestamps, orders/history come from recorded telemetry with their own times, live vs paper derives from the deployment, account-wide value change is not strategy-only profit, and it returns a text summary plus a botspot.trade link with an interactive panel where supported. It also discloses staleness semantics for recorded vs current reads.

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 description is a long run-on block mixing purpose, workflow ordering, output description, price-attribution instructions, fallback procedures, and anti-duplication rules, with several near-redundant restatements ('Do not duplicate successful current reads' / 'do not add watchlist or risk-budget panels to restate...'). It is not front-loaded: the first sentence is routing advice rather than what the tool does.

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 does a good job describing what comes back: account value, holdings with signed unrealized P&L, recent orders with dates, source timestamps, a text summary and link, and an interactive panel. The main completeness gap is the unexplained limit parameter, plus the dense prose makes the operational rules harder to extract than they need to be.

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 parameter meaning. It implies the tool is scoped to 'one deployment' and references 'that deployment's exact brokerCredentialId', which loosely maps to deploymentId, but it never explains that parameter directly. The limit parameter (default 20, max 50) is never mentioned at all, presumably controlling order count, leaving a real gap.

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 does state a concrete resource and scope: 'Answers "How is my bot doing right now?" and "What did my bot do?" for one deployment' and 'Already renders account value and holdings with signed unrealized P&L, followed by recent orders.' That distinguishes it from order telemetry, run history, and logs. However, the opening sentence is workflow routing rather than a statement of what the tool does, so the actual purpose arrives late in a dense block.

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 routes the agent: call this before separate order telemetry, run history or logs; reuse the rendered panels rather than adding restating panels; recover once with get_broker_account_snapshot/get_broker_positions if broker data is unavailable; use logs/run artifacts for decision explanations instead of redundant cross-checks. When-to-use, when-not-to-use, and named alternatives are all present.

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