tgboard — Telegram Directory

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

No annotations are provided, so the description carries the full burden. It only says 'Detailed card' without specifying what behaviors to expect (e.g., idempotency, rate limits, or whether it only retrieves public resources). The description lacks behavioral details that would help an agent use the tool correctly.

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 extremely concise: two lines for purpose and then parameter explanations. Every sentence is necessary and there is no redundancy. The main purpose is front-loaded.

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 description covers the core functionality and parameters adequately. Since an output schema exists, it doesn't need to describe return values. It could be slightly more detailed about what 'detailed card' includes, but it's complete enough for a single-resource retrieval tool.

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%, but the description adds meaning: it explains that slug is 'The resource slug from a tgboard URL or a search result' and documents lang values and default. This goes beyond the schema's bare type/required info.

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 'Detailed card of one catalog resource by its tgboard slug' which clearly identifies the action (retrieve detailed card) and the resource (one catalog resource by slug). This distinguishes it from sibling tools like list_telegram_categories, search_telegram, and top_telegram_resources.

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 explains that the slug comes from 'a tgboard URL or a search result', providing context for when to use this tool. It also documents the lang parameter with allowed values. However, it doesn't explicitly state when not to use it or list alternatives, but the usage context is sufficiently clear.

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?

No annotations provided, so description carries full burden. It discloses 'live resource counts' indicating dynamic, likely read-only behavior. It does not explicitly state read-only or side-effect-free, but 'catalog categories' implies no mutation. Slight room for improvement on stating non-destructive nature.

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?

Extremely concise: two sentences with inline parameter docs. Front-loaded with the primary purpose and key information (live counts, slug usage). Every sentence adds value 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?

With only 2 optional parameters and an output schema present, the description adequately covers tool behavior: listing categories with optional filters and language selection. It hints at output containing slugs and counts, which is sufficient given the output schema provides details.

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%, so description compensates fully. It specifies allowed values for 'type' (channels, bots, apps, groups, stickers) and 'lang' (en, ru, it, es, fr, ar) with defaults, adding essential meaning beyond schema structure.

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 clearly states 'Catalog categories with live resource counts (use slugs in other tools).' It specifies the verb (list/catalog), the resource (telegram categories), and unique value (live counts, slug usage). It distinguishes from siblings like search_telegram and get_telegram_resource.

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 description explains when to use the tool (to list categories with counts) and that slugs are used in other tools, implying follow-up actions. It provides optional filter parameters but lacks explicit exclusions or alternatives, which is acceptable given sibling names suggest distinct purposes.

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?

No annotations are provided, so the description must disclose behavioral traits. It only describes parameters but does not mention whether the search is read-only, latency, pagination, or any side effects. Being a search tool, it's likely safe, but the description does not confirm this.

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 relatively concise, listing parameters in a clear 'Args:' block. It avoids unnecessary prose. However, it could be slightly more structured (e.g., bullet points) for easier parsing, but it is acceptable.

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 description covers all parameters adequately but lacks behavioral traits and usage guidance. Since an output schema exists, return values are documented elsewhere. Missing context includes result ordering, pagination hints, and interaction with other tools.

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 0%, so the description fully compensates. It explains each parameter: query (topic/name/keyword), type (filter with specific values), lang (language options with default), and limit (range 1-25, default 10). This adds significant meaning beyond the raw schema types.

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 clearly states 'Full-text search across the tgboard catalog of Telegram resources' with parameter details. The verb 'search' and resource 'catalog' make the tool's purpose clear. However, it does not explicitly differentiate from siblings like 'get_telegram_resource' or 'list_telegram_categories', which is a minor gap.

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 description provides no guidance on when to use this tool versus alternatives (e.g., get_telegram_resource, list_telegram_categories). It does not mention prerequisites or when not to use it. The usage context must be inferred from the name and parameters.

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?

No annotations are provided, so the description carries the full burden. It does not mention behavioral traits like read-only nature, rate limits, or pagination. However, for a listing tool, the description is adequate but could be enhanced.

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, front-loaded with purpose, and uses a clear bullet-like list for parameters. Every sentence adds value, with no wasted words.

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 has 4 parameters, no required ones, and an output schema exists, the description covers parameters sufficiently. However, it does not specify the return format (though output schema exists) or pagination beyond the limit parameter.

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 input schema has 0% description coverage, so the description compensates fully by explaining each parameter with allowed values, defaults, and one parameter (category) includes a reference to a sibling tool. This exceeds the baseline expectation.

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 clearly states the tool's purpose: listing the most-followed Telegram resources with optional category filtering. It uses specific verbs and resource, and differentiates from siblings by referencing list_telegram_categories for category slugs.

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 description provides explicit guidance on each parameter, including allowed values and defaults, and mentions alternative tools for category lookup. However, it lacks explicit when-not-to-use conditions or direct comparison with search_telegram.

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