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 of disclosing behavior. It only says 'Detailed card,' which implies a read operation but does not explicitly state read-only, idempotency, error handling for missing slugs, or any rate-limit/auth requirements. This is a meaningful gap for a tool with no annotation support.

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 three short lines: a main sentence followed by an args list. It is front-loaded with the core purpose and contains no filler. Every sentence earns its place.

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 (one required param, one optional with default) and the presence of an output schema, the description covers the essential invocation details. The only omission is behavioral context (errors, side effects), which is minor for a read-only lookup but would be improved with a note. Overall it's sufficiently complete for correct invocation.

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 the description must explain parameters, and it does. It defines slug as 'the resource slug from a TGBoard URL or a search result' and lang with allowed values ('en | ru | it | es | fr | ar') and default (en). This fully compensates for the lack of schema descriptions.

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 'Detailed card of one catalog resource by its TGBoard slug' clearly states the verb (get detailed card) and resource (catalog resource). It differentiates from siblings like list_telegram_categories, search_telegram, and top_telegram_resources by emphasizing a single item lookup. This is unambiguous enough for an agent to select it for individual resource details.

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 implies when to use the tool: when the agent has a specific TGBoard slug, either from a URL or a previous search result (stated in the slug arg). It doesn't explicitly exclude alternatives, but the single-resource purpose and slug arg make the context clear. A stronger version would mention 'use search_telegram first if you don't have a slug,' but this is adequate.

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?

With no annotations, the description carries the full burden. It discloses that counts are 'live', which is useful, but does not state whether the operation is read-only, whether authentication is required, or any ordering/pagination behavior. For a simple catalog listing this is acceptable but not comprehensive.

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 compact and efficient: a one-sentence purpose with an actionable slug hint, followed by a terse args block. No filler or redundant 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?

Given the output schema exists, return-shape details are not needed. All parameters are fully described, the slug usage context ties it to sibling tools, and the optional/default behavior is clear. Minor gaps like pagination or explicit read-only status do not prevent correct selection and invocation.

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 the description is the only source of parameter meaning. It thoroughly documents both parameters: type with its allowed filter values and lang with its allowed values and default. This adds substantial value beyond the bare 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 clearly states the tool's purpose: 'Catalog categories with live resource counts' identifies the resource and core behavior. The note 'use slugs in other tools' differentiates it from sibling tools like get_telegram_resource and search_telegram, positioning it as the category-reference entry point.

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 clear context that this tool supplies slugs for use in other tools, and the optional type/lang filters suggest how to scope the request. However, it does not explicitly state when to prefer this tool over the siblings or mention any exclusions.

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?

Annotations are absent, so the description carries the full disclosure burden. It does state the search behavior ('Full-text search...'), supported type filters, language selection, and a 1-25 result limit, which are useful operational details. However, it does not mention whether the search is read-only, case-insensitive, or subject to auth/rate limits, leaving the safety profile implicit.

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 sentence followed by a compact bullet list, one line per parameter. It front-loads the tool's purpose and avoids redundant prose. Every line earns its place.

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?

All four parameters, including defaults and allowed values, are fully specified, and an output schema exists to define return values. The only substantive gaps are the absence of usage alternatives and behavioral caveats (e.g., whether results are limited to public resources). For a straightforward search tool, this is largely 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 description coverage is 0%, so the Args block is the only source of parameter semantics. It explains query (topic/name/keyword), type (enumerates channels|bots|apps|groups|stickers), lang (enumerates languages and default), and limit (range and default). This fully compensates for the bare input 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 opens with a specific verb and resource: 'Full-text search across the TGBoard catalog of Telegram resources.' This clearly distinguishes it from siblings such as get_telegram_resource, list_telegram_categories, and top_telegram_resources, which all imply different operations. No ambiguity remains about what action the tool performs.

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?

No sentence addresses when to use search_telegram versus get_telegram_resource, list_telegram_categories, or top_telegram_resources. The purpose statement implies a search scenario, but there are no explicit conditions, exclusions, or alternatives. An agent must infer selection criteria from the tool's name alone.

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?

With no annotations, the description carries the burden of behavioral disclosure and does so well: it explains filtering by type, category, language, and limit, and provides defaults, allowed values, and the numeric range for limit. It does not mention auth, rate limits, or error behavior, but for a read-only list operation these are less critical.

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 opens with a clear one-sentence summary and then uses a compact Args block. Every line adds useful information and there is no redundant or verbose content.

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?

All four optional parameters are fully documented with types, defaults, allowed values, and constraints. The description also connects to a sibling tool for category slugs, and since an output schema exists, the lack of return-format details is not a gap. The tool is simple enough that this description is sufficient for correct invocation.

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 the description must fully document parameters, and it does. Each parameter receives its allowed values or format: type lists all five options, category provides an example and source, lang enumerates supported languages, and limit specifies the 1-25 range with default.

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 identifies the tool as returning 'the most-followed Telegram resources' with an optional category filter. It does not use an explicit verb like 'list', but the meaning is unambiguous and the sibling tools (search, get single resource, list categories) are clearly distinct in scope.

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 context is implied through parameter guidance such as 'Optional category slug' and the cross-reference to list_telegram_categories for valid category values. However, it does not explicitly state when to prefer this tool over search_telegram or get_telegram_resource, leaving some routing decisions to the agent.

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