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

Annotations already declare readOnly/idempotent/non-destructive and closed-world; the description reinforces this with "Nothing is stored" and "Countries outside its table are named, never guessed", the latter directly corroborating openWorldHint=false. It also discloses methodology an agent could not infer: statutory rates as of 2026, US 15% with W-8BEN, European funds paying no withholding.

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-loads the core computation in the first clause and keeps every later detail (rates, edge cases, no storage) relevant. It is dense and slightly run-on across three long sentences, which keeps it just under 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?

An output schema exists so return values need no explanation, and the description covers the remaining gaps an agent needs: rate assumptions, unknown-country handling, no persistence, and residence-specific behavior. Nothing required to call it correctly is missing.

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 meaning beyond the schema by explaining that dividends are gross annual figures identified by ticker or country code and by describing the residence-dependent French 2047 credit treatment. This goes beyond restating field definitions.

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?

States a specific verb (computes) and a precisely scoped resource: source withholding, treaty rate, and over-withholding on a per-payer dividend list, plus the French 2047 credit. An agent can tell this apart from sibling tax tools like tax_loss_harvest 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?

Provides concrete user-question triggers ("how much Swiss tax do I lose on Nestlé dividends", "which of my dividends are over-withheld") that make the intended use unambiguous. It stops short of naming an explicit alternative or a when-not-to-use condition, so it sits below a 5.

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