Limzo Telegram Group Stats

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

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds useful scope context: network-wide coverage, 7-day/all-time windows, durable lifetime totals, and top groups. It does not contradict annotations. Since the output schema exists, the lack of return format description is acceptable.

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 a single, front-loaded sentence listing key outputs, followed by one concise sentence for guidance. No wasted words; every clause adds 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?

The tool is simple (0 params) and has an output schema. The description thoroughly covers the returned data (metrics, timeframes, totals, top groups) and provides usage context. It is complete and 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?

There are zero parameters and schema description coverage is 100% (vacuously). No parameter explanation is needed. The description adds meaning about what data is returned, which is beyond the empty schema.

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 states a specific verb ('Call this for network-wide numbers') and clearly resources ('all public Telegram groups tracked by Limzo'), with an enumerated list of metrics. It is distinct from siblings: 'For finding a specific group, prefer list_groups' explicitly differentiates it.

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 provides an explicit alternative: 'For finding a specific group, prefer list_groups.' This gives clear when-to-use/when-not-to-use guidance and names the sibling tool.

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

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

Beyond the readOnlyHint annotation, it discloses that the tool never includes verbatim member messages, and that wider ranges silently fall back to 7d for free groups, advising to check `range.key`. This gives critical behavioral insight.

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 front-loaded with the usage trigger and efficiently packs the return shape, caveats, and privacy note into a single coherent paragraph. No word is wasted.

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 the tool's simplicity, the description covers the purpose, parameters, return structure, and edge cases (paid plan fallback). The output schema and annotations handle the rest, making this fully complete.

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?

The schema covers both parameters, and the description adds a concrete example for slug ('hipo') and clarifies the range fallback behavior and default. This augments the schema's basic explanations.

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 explicitly states the tool retrieves stats for a specific Telegram group when users ask about activity, health, leaderboard, mood, or trends. It differentiates from get_global_stats by emphasizing 'specific group' and providing the slug URL format.

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 when-to-use triggers like 'activity, health, leaderboard, mood, or trends of a specific Telegram group.' It does not explicitly instruct when not to use or name alternatives, but the specificity to a single group versus the global stats sibling is implied.

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

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

The annotations provide readOnlyHint, but the description adds significant behavioral detail beyond that: query matching is case-insensitive over specific fields, lang filters by a 'meaningful share' of member writing, and total_matches indicates when more groups matched than were returned. These are non-obvious traits not present in the schema or 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 concise yet dense, using three sentences to cover purpose, filter behavior, and return fields. The last sentence is long but lists useful output fields. Every sentence earns its place, though slightly more structure (e.g., separating return fields) could improve scannability.

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?

The tool has 3 optional parameters, a read-only annotation, and an output schema. The description fully covers the tool's purpose, parameter semantics, and return fields (including total_matches for result truncation). It even provides enough detail to use the tool without needing the output schema, so it is contextually complete.

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 coverage is 100%, so the baseline is 3. The description adds semantic value by specifying that query searches title/username/slug/description and that lang uses ISO 639-1 with a meaningful-share heuristic. However, it does not mention the limit parameter, which is only described in the schema, so it doesn't fully elevate above baseline.

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 states exactly what the tool does: 'discover Telegram groups tracked by Limzo' for browsing, filtering, or finding a slug for get_group_stats. It clearly distinguishes from sibling tools by positioning list_groups for directory discovery and get_group_stats for group-specific stats.

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 explicitly says when to use this tool: 'to browse the directory, filter by language, or find a group's slug for get_group_stats.' It also explains the two filtering modes (query/lang) and that omitting both lists top groups, giving clear usage context without ambiguity.

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