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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description goes well beyond them: it explains the two-phase commit (estimate writes nothing, write fails 'if the save started over a search the estimate did not announce'), cost implications ('charged per check at each Source's credit rate'), and the destructive semantics of enabled=false ('removes its checks; its searches stay stored'). No contradiction with 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 very long, but it is front-loaded with the core purpose and the critical estimate/write workflow before the per-source detail block. Each sentence carries real information for a complex tool; the density is justified, though the wall-of-text per-source section could be better broken up. Minor structural critique only.

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?

No output schema exists, yet the description explains return semantics explicitly: 'monthlyCredits before and after, and resetSearches' and 'applied says which of the two happened: only applied=true is a save.' It also covers the failure condition, cost, and per-source behavior. For a 7-parameter two-phase mutation tool, nothing an agent needs 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?

Despite 86% schema coverage, the description adds substantial value: it clarifies the mode enum semantics (estimate takes no token, write requires it), explains the searches replacement behavior ('Keep the id of each search you keep'), documents refreshIntervalSeconds bands, and provides an exhaustive per-source guide to overrides with a concrete ai_answers example. This far exceeds the baseline for high-coverage schemas.

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 precise verb pair (add/replace) with a specific resource (one of a keyword's sources) and an explicit scope constraint: 'leaving every other Source untouched.' The title and first sentence align, and the description clearly differentiates from siblings like keyword_source_manage and keyword_estimate by naming them and their distinct roles.

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 an explicit when-to-use protocol: 'Call keyword_estimate first, show the person the monthlyCredits it returns, and send its estimateToken only after they agree.' It also names exclusions and alternatives: 'To stop it for a while, use keyword_source_manage instead' and 'switch coBrandsEnabled with keyword_update.' The estimate-then-write sequence is unambiguous.

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