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

Annotations only cover destructiveHint=false, so the description carries the real burden and does: encryption at rest, values never returned to MCP (only metadata), per-broker validation driven by the broker field, and explicit negative rules ('Do not pass ALPACA_IS_PAPER; BotSpot derives it from paperOrLive'). That is exactly the kind of consequence/constraint an agent cannot get from the schema.

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 critical rules are front-loaded, which is good, but the per-broker block is repetitive: 'Example credentialValues' appears ten times and the 'Do not pass X_IS_PAPER' rule is restated across four brokers. The detail is largely necessary given no broker enum, but it could be compressed into a table-like form, so length is close to excessive rather than optimal.

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 4-required-param mutation with a nested free-form object, no output schema, and only a destructiveHint annotation, the description supplies the missing pieces: what is stored, what is returned (metadata only), what is validated, and what must not be sent. An agent has enough to construct a valid call for every supported broker.

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 does heavy lifting: it explains the broker field's role and lists the accepted broker slugs (alpaca, tradier, schwab, tradovate, projectx-topstepx, weex, bitunix, kraken, coinbase), details credentialValues keys per broker, and clarifies paperOrLive indirectly (derived IS_PAPER flags). displayName is never explained, which keeps it off a 5.

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 and resource: stores broker credential material in Vault and returns only metadata. The scope statement ('broker login/trading credentials only') plus the explicit hand-off to saved_env_vars for non-broker secrets distinguishes it cleanly from the nearest sibling.

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?

Gives explicit when-to-use ('broker login/trading credentials only'), when-not-to-use ('do not put data-provider API keys, screener rows, CSV data... here; use saved_env_vars(action="create")'), and a behavioral rule for downstream deployments ('do not add a brokerCredentialId by default; let the user choose on the approval page'). Alternatives are named rather than implied.

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