tg_translate

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the max-20 message_ids constraint and the two mutually-exclusive input modes, which is useful context beyond the annotations. It does not describe output format or error behavior, but that is a minor gap given the annotation coverage.

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 front-loaded: one clear summary sentence followed by a terse, useful arg list. Every sentence adds information, and there is no repetition of schema names or annotation fields. The examples and max-limit note are efficient rather than 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?

Given there is no output schema, a note about return value would be helpful, but the core call contract is otherwise complete. All four parameters are semantically explained, the two operational modes are specified, and the annotation set covers side-effect safety. The tool is simple enough that an agent can invoke it correctly with the provided information.

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 carry the full burden of parameter semantics. It does this well: to_lang is explained as a target language code with examples, chat is tied to where messages live, message_ids is constrained with 'max 20', and text is explicitly contrasted as an alternative. It lacks clarity on required relationships between args (e.g., whether chat is needed when message_ids is used), but it substantially compensates for 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 opens with a specific verb and resource: 'Translate messages (or any text) with Telegram's own translator.' This clearly identifies the tool's function and distinguishes it from related siblings like tg_transcribe (transcription) or tg_summarize (summarization). The text-and-message duality is stated upfront, leaving no ambiguity about what the tool does.

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 implicitly provides usage guidance through its args: use chat+message_ids for translating existing messages, or text for translating arbitrary text. It also gives a concrete language-code example with 'e.g. "ru", "en", "de"'. However, it does not explicitly state when not to use this tool or name alternatives, so it stops short of a full 5.

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