subscribe

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose two useful traits: that only subscribed chats deliver events, and that this is the sole entry point for raw thread ids. However, it omits idempotency (does re-subscribing error or overwrite?), permission requirements, and what happens to an existing alias on conflict.

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?

Front-loaded with the purpose, then the key scoping rule, then a structured Args block. Efficient and skimmable, with only minor redundancy between the alias definitions.

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?

An output schema exists, so return values need not be described. For a two-parameter mutation tool the description covers purpose, sourcing of ids, the alias fallback, and the side effect of subscribing; only edge-case behavior (re-subscribe, alias collision) is missing.

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 compensate, and it largely does: chat_id is explained with a concrete example value, and alias is defined semantically plus given a fallback rule ('Derived from the thread title if omitted').

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?

States a specific verb (Subscribe) and resource (Instagram thread), plus a secondary effect (assign a short alias). It also explicitly positions itself as 'the ONE place a raw thread id is entered', which distinguishes it from list_threads/search_threads and the other 25 siblings.

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?

Gives clear context for when this matters ('Only subscribed chats deliver events') and names where chat_id comes from (list_threads or search_threads). It stops short of explicitly contrasting with unsubscribe/list_subscriptions or stating exclusions.

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