ads_tg_resource_list

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

With no annotations, the description carries the full behavioral burden; it usefully discloses that results come from the local catalog (no live Telegram fetch), that project_id defaults to 'neron', and that participant data is never returned. It omits pagination/ordering behavior, what the empty-result case looks like, and any permission caveats.

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?

A single, front-loaded sentence with no filler; the resource, storage location, default scope, and privacy guarantee are all packed in without redundancy.

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?

Six undocumented filter parameters with zero schema coverage and no output schema mean the description should explain what the filters mean and roughly what a returned resource looks like. It covers only the default project and a privacy guarantee, leaving the bulk of invocation semantics unaddressed.

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 6 parameters, and the description only addresses project_id's default. It says nothing about what type, status, rules_status, or membership_status filter on, nor how limit interacts with the enums—so the agent must guess the semantics of the four enum filters.

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?

Names a specific verb and resource ('List generic Telegram groups and channels') and scopes it to the local tg_resources catalog, which separates it from remote-fetch siblings like ads_telegram_public_posts_search and from the write-side ads_tg_resource_upsert. The qualifier 'generic' and 'saved in the local ... catalog' helps distinguish it from ads_tg_resource_post_list, though that contrast is implied rather than stated.

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?

Usage is implied by 'saved in the local tg_resources catalog; defaults to the Neron project', so an agent can infer this is the read side of the resource catalog. However, it never names an alternative or a condition that selects one tool over another (e.g., when to use this vs. ads_tg_resource_post_list or ads_telegram_account_search).

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