ads_tg_resource_upsert

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

With no annotations at all, the description carries the full disclosure burden. It usefully clarifies that nothing is executed on Telegram, but says nothing about update semantics for this 17-field upsert — whether omitted fields are cleared or preserved, idempotency keys, validation failures, or permission requirements — which are the behaviors an agent most needs to know before writing.

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 short sentences, no redundancy, with the core action front-loaded and the safety scope as the follow-up. Nothing here is padding.

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 17-parameter mutation with no annotations, no output schema and zero schema descriptions, the definition is far too thin: it never mentions what the tool returns, how conflicts are resolved, or what the many status/timestamp fields mean. The one genuinely useful disclosure (metadata-only, no Telegram side effects) is not enough to make the definition self-sufficient.

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 17 parameters, including four enums (type, status, rules_status, membership_status) with no hint of their meaning or default behavior. The description adds only the vague notion of 'metadata' and does not explain a single field, so the agent must infer the entire payload shape from property names.

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 pair ('save or update') plus the exact resource ('one Telegram group or channel in the generic local resource catalog'), which is far more precise than the name alone. It is distinguishable from ads_tg_resource_list by the singular/upsert framing, though the description never names that sibling explicitly.

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 second sentence establishes an important boundary — this is catalog/metadata storage, not a live Telegram action — which implicitly routes the agent away from join/send tools. However it never says when to prefer this over sibling tools like ads_tg_resource_post_record or ads_tg_resource_list, nor any preconditions for calling it.

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