tg_contacts

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

No annotations are provided, so the description shoulders the transparency burden. It discloses behavioral details: birthdays are 'sorted by date', top is 'ranked by Telegram itself', and it clarifies the query limitation. This gives the agent a good sense of what the tool returns without needing to call it. It doesn't mention network/permission concerns, but for a contacts lookup this is acceptable.

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 front-loaded with a concise purpose sentence, then cleanly structured as an args list with one line per parameter, using consistent formatting for kind values. Every sentence adds value; no fluff or repetition.

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 tool has an output schema, so return formatting is already covered. The description covers all parameter semantics and the distinct modes, making the tool's behavior fully understandable for an agent. Given the simplicity of a contacts list, this is 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 coverage is 0%, but the description fully documents all three parameters: query (filter by name or username, constrained to kind='all'), limit (how many rows), and kind (enumeration of five values with explanations). This is a model of parameter documentation, adding meaning well beyond the schema's bare property definitions.

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 'Your contacts, or a slice of them', clearly identifying the resource and implying retrieval. The detailed kind list (all, birthdays, top, online, blocked) further specifies the scope and distinguishes the tool's multiple modes. However, no explicit verb like 'list' or 'get' is used, making it slightly less direct than ideal.

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 for when to use each kind, e.g., birthdays 'answers whose birthday is coming up' and top shows 'people, groups and channels this account interacts with most'. It also notes query only applies to kind='all', which is a useful exclusion. It doesn't name alternative sibling tools, but the guidance is sufficient for most use cases.

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