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

Annotations already cover the read-only, idempotent, closed-world profile, and the description adds real context: no cost, no account required, no silent expansion, and the PECR corporate-subscriber default for email audiences. The GDPR lawful-basis sentence is tangential to invoking this specific tool, so it is useful framing rather than direct behavioral disclosure.

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 workflow and scoping information are front-loaded and earn their place, but the closing compliance sentence (UK GDPR Article 6(1)(f), PECR sole-trader exclusion) is long and only loosely tied to selecting or invoking this expansion tool. The result is an overlong description where the last third is boilerplate.

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 not be described, and the description supplies the workflow, cost, and compliance defaults an agent needs. The main gap is that dataset availability (ie_contacts and global_contacts not yet served) is left entirely to the schema despite being a likely failure mode.

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; the description goes further by explaining what the expansion sets mean in practice (plurals, department synonyms, ampersands, abbreviations like CEO) where the schema only lists enum names. It also illustrates a bundle value ('sdm'), though it does not touch mode or the dataset availability caveat, which the schema handles alone.

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?

Specific verb and resource: 'Expands title keywords into every matching title' with concrete examples of what expansion covers (plurals, department synonyms, ampersands, abbreviations such as CEO) and the alternate bundle-resolution behavior. It is clearly distinguishable from count_audience, which it names as the downstream step rather than a competitor.

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?

Explicit sequencing: use it before counting so the user can review and edit the expanded titles, then place the returned filter into the audience and call count_audience. It also states the negative guarantee ('nothing is expanded silently'), which tells the agent why this step must not be skipped.

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