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

Beyond the annotations, it discloses that credentialValues replaces saved credential values when provided and that raw values are never returned. It also explains broker-specific validation and warns against passing derived paper/live flags, which prevents incorrect writes.

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 purpose, replacement semantics, and usage warnings are front-loaded before the long broker-specific key reference. The broker sections are lengthy but each earns its place because the schema has no parameter descriptions and correct credentialValues keys are essential for successful invocation.

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 mutation tool with nested credentialValues and no output schema, the description covers ownership, replacement behavior, return-value secrecy, and broker-specific formats thoroughly. It could be more complete by stating whether omitted metadata fields remain unchanged and by describing id/displayName update semantics.

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 compensate; it does so extensively for broker and credentialValues with exact key names and examples per broker. It also implies paperOrLive behavior through the paper/live derivation notes, but it leaves id and displayName largely undocumented.

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 clearly states that it updates broker credential metadata and optionally replaces Vault-stored values for the authenticated owner. It distinguishes this from creating or deleting credentials by its update scope and explicitly limits it to broker login/trading credentials.

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 gives explicit when-to-use guidance, including broker login/trading credentials only, and warns not to attach a brokerCredentialId to a deployment by default. It also names the alternative for non-broker secrets: saved_env_vars(action="create").

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