ads_telegram_ai_search_query_upsert

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

With no annotations, the description does useful work by disclosing that this only changes local SQLite and never performs external search or messaging side effects. It still omits mutation details such as upsert key behavior, whether existing fields are overwritten, permission requirements, and response characteristics.

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 two tight sentences with the purpose and key non-side-effect constraint front-loaded. Every sentence adds relevant information and there is no filler.

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?

Given 10 parameters, 0% schema description coverage, no annotations, and no output schema, the description is too sparse for an agent to call the tool correctly across most fields. It covers the high-level upsert and local-only scope but leaves parameter semantics and mutation behavior largely undocumented.

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 description coverage is 0% across 10 parameters, so the description must explain parameter meanings, but it only implies the required 'query' via 'search phrase.' It says nothing about notes, topic, intent, source, status, language, metadata, priority, or project_id.

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?

The description uses a specific verb and resource: 'Save or update one Telegram AI search phrase,' and adds the intended scope, 'for later discovery and demand analysis.' It also distinguishes this from search execution by saying it 'never searches or sends messages,' though it does not explicitly name a sibling alternative such as the query list or run tools.

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 gives clear context for use ('for later discovery and demand analysis') and an explicit exclusion ('never searches or sends messages'). However, it does not name specific alternatives like ads_telegram_ai_search_query_list or ads_telegram_ai_search_run_list to make routing fully explicit.

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