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

Annotations already mark this as non-read-only and destructive, but the description adds meaningful behavior: equal-weight top assets vetted live, provenance and caveat, create=true producing a user-owned vehicle, default vehicle kind, and payment from the user's own balance. It could say more about what exactly is destructive or irreversible, but it adds substantial context beyond the annotations.

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 compact and front-loads the core basket-building purpose before covering create=true behavior and payment. It is dense but largely earns its clauses; the parenthetical about no key needed is useful rather than 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?

For an 8-parameter, non-idempotent, destructive creation tool with no output schema, the description covers purpose, auth/cost context, and vehicle creation reasonably well. However, it does not clarify publish versus create, size/title semantics, or how this tool relates to sibling basket tools, leaving meaningful gaps.

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 only 25%, so the description must compensate. It adds useful meaning for theme, asset_class, create, and vehicle_kind, including the default vehicle behavior, but leaves size, title, and publish unexplained.

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 this tool builds an equal-weight top-asset basket for a theme/subtheme or custom theme within a chosen asset class, and that create=true turns it into the user's own vehicle. It distinguishes the create behavior from a plain basket, though it does not explicitly name the closest sibling tools.

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 description implies when to use it: for a theme/subtheme/custom theme in stocks or crypto, and with create=true for a signed-in user to make an event card or AI Index Basket. It does not explicitly compare against alternatives such as theme_journey_edit_basket, theme_journey_my_baskets, or preview_card_basket.

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