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

Beyond the annotations it discloses the permission model (owner only), that no sign-in is required for the self-sent transaction, that missing CoW approvals get added, that the call itself builds nothing, and that it is a safe re-check. The one ambiguity is that "this OPENS one" and "approvals are added" read like real mutations even though the call is framed as a prediction — a sentence making clear these are counterfactual/simulated effects would remove all doubt about the readOnlyHint.

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-loaded with the core guarantee ("building nothing") and then the validation rules, branch behaviour and handoff, with no filler sentences. The semicolon-chained validation list is dense and takes a second read, which keeps it off a 5.

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 three-parameter preview tool with full schema coverage, an output schema and rich annotations, the description covers purpose, permissions, branch semantics, validation and next step — everything needed to invoke it correctly. Only the read/write framing around opening a portfolio and adding approvals leaves residual ambiguity.

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 100% schema description coverage the schema already documents all three parameters and their nesting, so the baseline is 3. The description does add enforced constraints that are not in the schema — tokens must be listed and Active, each weight at least the minimum, no duplicate tokens, at most the maximum positions, entries + cash = 10000 bps — but these are framed as aggregate validation rules rather than per-parameter meaning, so it is a modest lift over the schema.

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 opening clause gives a specific verb and resource ("Check a proposed set of stocks and weights") and immediately scopes it against the write-side sibling ("building nothing... Pass previewId to prepare_stock_basket"). An agent can tell it apart from prepare_stock_basket, preview_deposit and preview_withdraw without opening any 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?

It states the two outcome branches explicitly — no portfolio yet means one is opened at a predicted address; otherwise the owner's targets are replaced — and names the exact next step ("Pass previewId to prepare_stock_basket"). It does not spell out a when-not-to-use case (for example, calling prepare_stock_basket directly without previewing), so it stops just short of 5.

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