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

Beyond the annotations it discloses the traits an agent most needs: allowlist replaces the entire saved list (the concrete thing destroyed, matching destructiveHint), the change takes effect on the next call (immediacy, matching idempotentHint), and admin permission is required. It leaves failure behavior and validation errors unexplained, but the core mutating semantics are well covered.

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 purpose leads, the mode semantics follow, and the operational caveats (exemptions, list replacement, admin, timing) come last in a single dense paragraph. The long parenthetical describing the screen flow is informative but slightly overstuffed; otherwise there is no wasted wording.

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?

With annotations covering safety hints, a 75%-described schema, and an output schema, the description adds exactly the missing pieces: what each mode does, who is exempt, that allowlist is a full replacement, and that changes apply immediately. An agent can call this correctly without further context.

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?

The description supplies the real meaning of the mode enum values rather than just listing them, including what screen actually does to the caller and what label means operationally, which is genuine value above the schema. dry_run and business_id are left entirely to the schema, but with 75% coverage the schema already carries those, so the description covers the parameter that most needs interpretation.

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?

"Change how the business screens scam calls, or which numbers are never screened" gives a specific verb (change) plus two concrete resources (screening mode, allowlist), and the mutation framing clearly separates it from the read-side get_scam_screening sibling without naming it.

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 explains the three mode choices and their consequences, notes label is the default when nothing is blocked, states that known customers and the team are exempt, and flags the admin prerequisite. It stops short of explicitly routing an agent to get_scam_screening to read current settings or recommending dry_run first, so it is strong context rather than full when/when-not guidance.

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