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

Goes well beyond the annotations by disclosing what run_now actually does (starts read-only snapshot compute via Bot Manager and the Vault-backed runtime secret path), ownership scoping ("owned by the authenticated user"), and repeated sanitization guarantees (no raw credentials, Vault ids, ARNs, secret values, full account numbers). It reconciles with readOnlyHint=false by framing run_now as an execution trigger. It does not state that repeated run_now calls are non-idempotent (each call starts a new run) or note rate/cost limits, which is the remaining gap.

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-loading is strong (the realtime alternative appears in sentence two) and the per-action headings make it scannable. However, "Raw broker credentials and full account numbers are never returned" is restated in four separate action sections, and the list_deployments fallback guidance appears twice, so a meaningful share of roughly 450 words is redundant padding.

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 and eleven parameters across five actions, the description carries return-shape disclosure itself and does so: list returns accountDisplay/lifecycle/last run/portfolio value/cash/position count, diagnostics returns Node identity plus scheduled/ECS status, positions returns normalized snapshot rows. It also preempts the account-labeling trap ("Never infer an account suffix from brokerCredentialId").

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 coverage is 100%, so the baseline is 3, but the description adds action-conditional structure the flat schema does not convey: "Only send the fields listed for that action," per-action "Required fields: brokerCredentialId," and "No other fields required" for list/positions. It also explains the key semantic choice for positions — omit brokerCredentialId to get one aggregate call that preserves account-to-position mapping rather than fanning out.

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?

Opens with a specific verb+resource ("Read stored daily broker snapshot automation data") and immediately separates itself from the realtime sibling: "For realtime holdings use get_broker_positions." Each of the five actions is then enumerated with its own heading and one-line purpose, so an agent can tell list/portfolio/positions/diagnostics/run_now apart without opening the 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?

Explicit when-not-to-use for the riskiest misinterpretation: positions "only when the user explicitly asks about snapshot history... for realtime holdings questions like 'how much Tesla stock do I own?', use get_broker_positions with symbol=TSLA." It also supplies a documented fallback chain (list_deployments(status="running", limit=50) then get_deployment_position_telemetry) and warns that empty snapshots do not prove running deployments have no positions.

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