ads_telegram_ai_keyword_rebuild

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

With no annotations, the description carries the full burden and does well: it discloses the data sources read, the side effect of reset=true (replaces derived aggregate and observation tables), what is persisted ('only normalized keywords and source metadata'), and a negative guarantee ('never sends messages'). It does not state whether rebuilds are idempotent or what happens to prior aggregates when reset is false.

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?

Two sentences, front-loaded with the action and sources, then the reset semantics and safety guarantees. The semicolon-chained second sentence is dense but every clause adds distinct information.

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 no-annotation, no-output-schema mutation tool, the description covers sources, destructive scope, stored fields, and absence of outbound messaging – enough to call it safely. The remaining gap is project scoping, which the schema leaves undescribed.

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?

reset is documented in both schema and description, and the description adds real meaning by tying it to specific derived tables rather than a generic 'rebuild'. project_id, however, is undocumented in both places (50% coverage) – nothing says what project scope applies or why the 'neron' default exists.

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 ('Rebuild') and resource ('demand keyword observations') plus the three source data sets it derives from, which implicitly separates it from ads_telegram_ai_keyword_observe (which records new observations) and ads_telegram_ai_keyword_list. It stops short of naming any sibling explicitly, so an agent must infer the boundary.

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?

The clause 'Set reset=true only to replace the derived keyword aggregate and observation tables' gives a clear when-to-use condition and an implicit warning against the destructive path. No alternative tool is named as a fallback for non-rebuild cases, so the routing guidance is one-sided.

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