tg_message

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, non-destructive), so the description productively focuses on content-level behavior. It discloses a genuinely surprising edge case: poll messages get a 'votes' block with counts and your own vote, a public poll additionally lists who voted for what, and an anonymous poll shows no voter list at all — not even to the author. This kind of conditional behavior is exactly what an agent needs to anticipate. It stops short of describing response shape or error behavior, but the behavioral specifics provided are strong.

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 summary line is front-loaded and information-dense, the poll paragraph adds an important conditional behavior in just two sentences, and the Args list is compact and scannable. There is no filler or repetition of what the schema already states.

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?

For a 4-parameter read tool with no output schema, the description documents every parameter, the core payload, and the poll edge case that would otherwise surprise an agent. The main gap is the concrete shape of the returned message object (field names and nesting), which the absence of an output schema leaves unstated. Still, an agent has everything needed to invoke it correctly in the common and poll cases.

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 carries the entire parameter-documentation burden — and it fully delivers. chat is explained as accepting 'chat id, @username, exact title or "me"', context is glossed as 'also return this many messages before and after it', replies as 'also return this many replies to it (threads/comments)', and message_id as 'the message to inspect'. Every one of the four parameters receives meaning the bare schema lacks.

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 opening line, 'One message in full: reactions, inline buttons, how many people read it, plus optional surrounding context and its reply thread,' names the exact resource (a single message) and its distinguishing payload. The 'one message' scope sets it apart from list-style siblings like tg_history or tg_view, and the explicit mention of context and reply thread reinforces that this is a deep read of a single message, not a listing tool. A verb is implied rather than stated, but the purpose is unambiguous and clearly differentiated.

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 conveys its use case implicitly — reach for it when you need full detail of one message (reactions, buttons, read counts, poll vote breakdown) with optional surrounding context or thread replies. However, it never states when not to use it or names any alternative tool for simpler message reads, and none of the many siblings is referenced for routing. An agent must infer applicability from the feature list rather than being told.

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