tg_activity

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

Even with readOnlyHint and idempotentHint annotations, the description adds substantial behavioral detail: days are UTC and newest first, archive is included, incoming and outgoing are counted separately, and for all-message calendars it relies on sparse server positions that are exact up to ~2000 messages then sampled, with the reply explicitly saying so. This goes well beyond the 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 well-structured with a clear lead, a contrast to tg_unread, a mode explanation, an accuracy caveat, and a readable Args list. It is longer than strictly necessary, and the unexplained 'exact=true' reference adds minor noise, but most sentences carry useful information and the front-loaded purpose is strong.

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 both usage modes, all parameters, default behaviors, sampling caveats, and UTC ordering, which is impressive for a tool with no output schema. However, the mention of 'exact=true' is not backed by a schema parameter, and 'same tabs as tg_media' relies on the agent understanding an external tool's tabs, leaving slight gaps for a fully self-contained call.

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 descriptions are completely absent (0% coverage), but the Args section compensates thoroughly by explaining all eight parameters: since/until bounds and defaults, limit_chats, kind, include_own, per_chat, chat, and limit_days. It also gives concrete offset examples like '-6h' and '-30d', which the raw schema does not provide.

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 sentence states the tool's core function: 'Which chats had any conversation in a period — where did I talk today' — with a specific resource (chats) and action (find activity). It also explicitly differentiates from tg_unread by noting it covers already-read chats and owner-only conversations, and clearly describes the second calendar mode triggered by the chat parameter.

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 gives explicit when-to-use guidance: 'Unlike tg_unread this covers chats already read and chats where only the owner wrote, so it is the right start for a daily recap.' It also references related tools naturally, such as using tg_history to jump into a specific day and sharing attachment tabs with tg_media, showing the agent both the intended context and alternatives.

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