threads_get_post_insights

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

Annotations only declare readOnlyHint, and the description adds real context beyond them: the threads_manage_insights permission requirement and the null-vs-0 interpretation rule ('null means Meta did not return the metric; 0 means a zero counter'). That null/0 distinction is a meaningful behavioral disclosure. It does not cover rate limits or metric availability, but the core gaps an agent would trip on are addressed.

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?

Four short sentences, all front-loaded: purpose first, then parameter sourcing, then the permission gate, then the result-interpretation caveat. No filler or restated field names.

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 two-parameter read tool with an output schema, everything needed is present: what it reads, how to obtain both required IDs, the auth requirement, and how to read null versus zero values. Nothing essential to a correct call 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 does: it tells the agent exactly where each of the two parameters comes from (threads_list_accounts for account_id, the id field of a listed post for post_id). It does not restate the numeric-string format enforced by the schema pattern, but provenance is the more valuable missing piece and it is supplied.

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+resource ('Read insights') scoped to 'one of the connected account's own Threads posts', which implicitly separates it from threads_get_account_insights. It does not name the sibling explicitly, so differentiation is clear but not spelled out.

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?

It gives concrete provenance for both inputs ('Get account_id from threads_list_accounts', 'post_id from the id field of a post returned by threads_list_posts') and states the required permission threads_manage_insights. It stops short of explicit when-not guidance, such as directing the agent to threads_get_account_insights for account-level metrics.

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