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

With annotations already covering the read-only/idempotent safety profile, the description adds substantial non-obvious behavior: a ~90-day data window, follower thresholds for certain metrics, the empty-not-zero return semantics, and the required parameter combination for demographic metrics. These are exactly the traits an agent cannot get from the schema or 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?

Front-loads the metric scope, then layers constraints in three tight sentences with no filler. Dense but each sentence carries actionable information; nothing is redundant.

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 7-parameter read-only tool with no output schema, the definition covers purpose, retention limits, edge-case return behavior, and the demographic parameter contract. Rate limits and pagination are unaddressed, but nothing essential to correct invocation 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 coverage is 71%, and the description compensates by explaining the cross-parameter dependency that demographics require period=lifetime plus metric_type=total_value plus a timeframe and breakdown. It also enumerates allowable breakdown dimensions, adding meaning the schema only partially captures.

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 resource and scope: 'Account-level metrics (views, reach, engagement, followers, demographics)'. The 'account-level' framing implicitly separates it from sibling ig_media_insights, though it never names that sibling explicitly, so an agent must infer the boundary.

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?

Provides operational context (90-day retention, 100+ follower requirement) that tells the agent when data will exist, but gives no explicit guidance on when to choose this over ig_media_insights or other insight tools. Usage is implied rather than stated.

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

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

Annotations already declare the write/non-idempotent/open-world profile, and the description usefully adds the write-gate flag that annotations cannot express. However it omits other behavioral facts an agent would want: that the comment is publicly visible, that it cannot be edited, and that removal requires a separate tool.

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?

Two short sentences, front-loaded with the action and scope, then the gating constraint. No filler, no restatement of the title.

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 write tool with no output schema, the definition covers the action and the enablement gate but leaves the return value (does it yield a comment ID?) and rate limits unstated. Adequate, but the absence of an output schema means the description should carry more of that burden.

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 50%: 'message' is fully documented in the schema, while 'media_id' has a pattern but no description. The description partially compensates by stating the comment targets one of the account's posts or reels, implying media_id is a post/reel identifier, but adds no format or sourcing guidance beyond that.

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 (adds), resource (comment), and scope (top-level, on the account's posts or reels). The 'top-level' qualifier is exactly what separates this from the sibling ig_reply_comment, so an agent can route correctly without opening either schema.

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 a concrete operational prerequisite ('Requires IG_ENABLE_WRITES=true') that tells the agent when the call will fail, which is real context. It does not name alternatives (e.g. use ig_reply_comment for nested replies) or state when not to use it, so it stops short of a full 5.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the bar is lower, but the description adds real context: "Permanently deletes", "Cannot be undone", and the IG_ENABLE_WRITES=true environment gate. It doesn't say whether replies to the comment are also removed.

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?

Three short sentences, front-loaded with the operation and the irreversibility warning. Every sentence carries information and none is padding.

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 single-parameter destructive tool whose annotations already cover the safety profile, the description covers permanence and the write gate. Minor gaps remain: no mention of reply cascade behavior or failure modes.

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% for the single required comment_id parameter (only a numeric pattern is given), and the description adds no meaning about what the ID references or where to obtain it. With low coverage, the description is expected to compensate and does not.

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+resource ("deletes a comment") plus a scope qualifier ("on the account's media"), so the agent knows exactly what is targeted. It does not differentiate from sibling ig_hide_comment, which is a non-destructive alternative, so it falls short of a 5.

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?

No when-to-use or when-not-to-use guidance is given; the safer sibling ig_hide_comment is never mentioned as an alternative. The IG_ENABLE_WRITES=true note is a precondition, not routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds real value by enumerating the returned statuses (IN_PROGRESS/FINISHED/PUBLISHED/ERROR/EXPIRED), but says nothing about auth requirements, rate limits, or how a container reaches ERROR.

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?

A single front-loaded sentence that puts the resource first and the possible values second; no filler. It is a fragment rather than a full sentence, which slightly weakens readability but costs nothing in information.

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?

With no output schema, the enum of statuses usefully sketches the return values, which is the main thing an agent needs. However, the sole input parameter is entirely undocumented, leaving the tool callable only if the agent already knows where container_id originates.

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 has 0% description coverage and contains one parameter (container_id, numeric-string pattern). The description never mentions container_id, its format, or where the value comes from, so it does not compensate for the schema gap.

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?

Names a specific resource (media container) and the exact attribute returned (processing status), with the enum of possible values. It does not, however, distinguish itself from close siblings such as ig_get_media or ig_media_insights, so an agent must infer the difference from the name alone.

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?

There is no when-to-use guidance, no mention of prerequisites, and no reference to alternatives (e.g., using this after ig_publish_container to poll until FINISHED). The agent is left to infer the entire polling workflow.

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

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

Annotations already declare it read-only and idempotent, so the safety profile is covered. The description adds only that carousel children are included; it says nothing about permissions, ownership, rate limits, or error behavior for an invalid id.

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?

A single tight sentence that front-loads the resource and scope with no filler.

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?

With no output schema and no parameter documentation, the description should describe the return shape and the media_id format. It covers scope but leaves an agent unsure what fields come back or what a valid id looks like.

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%, so the description must compensate. It only implies that media_id selects one post/reel/story; it doesn't explain that the id must be numeric, where to obtain it, or whether carousel child ids are valid inputs.

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 (get) and resource (media) plus the accepted media types and that carousel children are included, which distinguishes it from ig_list_media. It doesn't explicitly name ig_list_media, so sibling differentiation is only implied.

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?

No guidance on when to use this versus ig_list_media or ig_media_insights; the agent must infer that this fetches a single object by id. There is no mention of prerequisites or error conditions.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so safety is covered. The description adds genuinely new behavioral context: Instagram caps results at the 20 most recent messages, which tells the agent the result set is truncated. It stops short of saying whether pagination exists to reach older messages.

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?

Two short sentences with no filler; the return-shape note comes first and the truncation caveat second. Telegraphic phrasing but nothing wasted.

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 single-parameter read tool with annotations covering safety and no output schema, the description covers purpose, return fields and a result limit. The only real gap is the meaning/acquisition of conversation_id.

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?

There is one parameter with 0% schema description coverage, and the description never explains conversation_id — not its format, pattern (^[\w-]+$), or where to obtain it. The word 'conversation' appears, but that does not compensate for the undocumented required parameter.

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 resource (messages of one conversation) and even previews the return fields (sender, recipient, text). This distinguishes it from ig_list_conversations and ig_send_message, though the verb 'Get' lives in the name rather than the description.

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?

Usage is only implied by the resource scope: fetch messages inside a single conversation. There is no explicit when-to-use guidance, no mention of the sibling ig_list_conversations for discovering a conversation_id, and no exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered without the description. The description's added value is the field inventory, which tells the agent what data comes back; it says nothing about token requirements, failure modes, or rate limits.

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?

A single fragment that front-loads the resource and lists returned fields with zero filler. Every word earns its place.

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?

With no output schema and no parameters, the description usefully enumerates the returned fields, which is the main gap it needs to fill. It could go further by noting that the account is the authenticated one and what happens on missing/invalid tokens, but for a trivial zero-arg read it is largely sufficient.

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 tool takes zero parameters, so the schema carries no semantics to compensate for and cannot be misunderstood. Baseline of 4 applies; there is no parameter ambiguity to resolve.

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 names a specific resource ('Profile of the connected professional account') and enumerates exactly what it returns (username, name, bio, followers, follows, media counts). It's clear which sibling it is not (media, comments, insights), though it never states a verb like 'retrieve' and relies on the title for that.

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 scope qualifier 'connected professional account' implies the usage context — fetching the authenticated account's own profile rather than another user's — which implicitly rules out most siblings. However, there is no explicit when-to-use statement, no mention of prerequisites (valid token) or rate limits, and no named alternative.

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

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

Annotations already declare the write/destructive/idempotent profile, so the bar is lower; the description adds the non-obvious operational gate that IG_ENABLE_WRITES must be true and clarifies the effect is a reversible public visibility toggle rather than removal. It does not explain rate limits or error behavior, but for a two-state toggle this is solid added context 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?

One sentence, front-loaded with the primary action, with the inverse case and the prerequisite packed into a parenthetical follow-up. No wasted words.

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?

With no output schema and only two parameters, the description covers the action, the inverse action, and the enabling flag. It could note whether hidden comments remain visible to the author or how failures surface, but nothing critical to invoking it correctly 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 carry the load; it does explain that hide=false re-shows the comment, adding real meaning beyond the bare boolean. However, comment_id (the only required param) gets no explanation of format or source, leaving half the parameters undocumented.

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+resource (hide a comment) and clarifies the toggle direction with "shows it again with hide=false", which implicitly separates it from the destructive ig_delete_comment sibling. It does not name any sibling explicitly, so distinction relies on inference rather than direct callout.

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 a real prerequisite (IG_ENABLE_WRITES=true), which is genuinely useful gating context, but offers no guidance on when to prefer this over ig_delete_comment or ig_set_comments_enabled. Usage is implied rather than specified.

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

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

Annotations already establish the safe read-only, idempotent, open-world profile, so the bar is lowered. The description adds value by naming what each item returns (author, likes, hidden flag), which matters since there is no output schema, but it says nothing about pagination behavior via 'after' or rate limits.

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?

A single tight sentence with the resource scope front-loaded and the returned fields appended. No filler, though the fragment style sacrifices a bit of clarity.

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?

With no output schema, the description usefully lists the returned attributes, but for a paginated list tool it omits how pagination terminates and any ordering semantics. Adequate but with clear gaps for a listing operation.

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 67%: 'after' and 'limit' are documented in the schema, while media_id has none. The description compensates slightly by clarifying that the media must belong to the account, but adds no format or identifier detail. Baseline 3 for schema doing most of the work.

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 resource (top-level comments) scoped to 'one of the account's posts or reels', and the qualifier 'top-level' implicitly separates it from ig_list_replies. It doesn't explicitly name a sibling, but the scope is unambiguous enough to distinguish it from the reply/comment-mutation tools.

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 phrase 'top-level comments' implies when this is appropriate versus ig_list_replies, but there is no explicit when-to-use, when-not-to-use, or named alternative. Usage is only inferable from the scope word.

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

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

Annotations already carry the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds genuine behavioral context beyond them: the sort order (most recently updated first) and a real filtering rule that request-folder threads inactive for 30 days are omitted.

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?

Three tight sentences with the core resource and ordering front-loaded, followed by the two behavioral qualifiers. No filler, though the user_id sentence largely restates schema content.

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 3-parameter, no-output-schema listing tool the description covers resource, ordering, and the request-folder exclusion adequately. It stops short on pagination mechanics ('after') and result shape, which an agent would need for correct invocation.

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 only 33%, with 'after' and 'limit' having no schema description at all. The description repeats the IGSID meaning already in the schema for user_id but says nothing about cursor pagination or the limit cap, so it fails to compensate for the coverage gap.

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?

Names the specific resource (direct-message conversations of the account) and states the ordering. It is clearly a listing tool distinct from ig_get_messages/ig_send_message, though it never explicitly names a sibling to contrast against.

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?

Explains the user_id narrowing behavior ('With user_id ... returns only the conversation with that person'), which gives implicit guidance on when to use that parameter. However, it offers no when-to-use vs alternatives guidance relative to siblings like ig_get_messages, and no prerequisites for account scope.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: result ordering (newest first), what each item carries (likes and comment counts), and that results are cursor-paginated — none of which appear in the structured fields.

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?

Two tight sentences with no filler; the resource/ordering/contents summary is front-loaded and the pagination instruction follows immediately. Every clause carries information the agent needs.

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?

With no output schema, the description must convey return shape, and it does cover ordering, engagement counts, and the cursor field. It stops short of naming the core media identifiers or type fields an agent would need to chain into ig_get_media or ig_media_insights, leaving a small gap.

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 100%, so the schema already defines `after` and `limit`, giving a baseline of 3. The description earns an extra point by linking the output field next_cursor back to the `after` input parameter, clarifying the pagination loop in a way the schema cannot.

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 resource (posts and reels of the connected account) and scope (newest first, with engagement counts), which implicitly separates it from ig_get_media, ig_list_stories, and ig_list_tagged_media. However, no sibling is named, so the agent must infer the boundary from the resource phrasing alone.

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 implies the listing context via 'connected account' and 'newest first', but never says when to choose this tool over ig_get_media (single item) or the other list tools. Pagination guidance is present but usage-vs-alternative guidance is left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that — it does not mention pagination via cursor, ordering, or what the reply objects contain, so it fails to enrich beyond the structured fields.

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?

It is a single short sentence and thus not bloated, but it is under-specified rather than concise — the one sentence it spends is ambiguous about whether the tool lists or creates replies, so it does not earn its place.

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 paginated read tool with no output schema, the description should at minimum indicate that it returns a page of replies for a given comment and mention cursoring. None of that is present, leaving the agent without the context needed to interpret results or paginate.

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 only 67%, and the undocumented parameter is comment_id — the single required input with a numeric pattern constraint. The description adds no meaning about comment_id (whose replies are returned) nor about the after/limit cursoring, so it does not compensate for the coverage gap.

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 title says 'List replies to a comment', but the description itself reads as 'Replies to a comment on the account's media' — a phrase that can be parsed as the verb 'replies' (i.e., posting a reply), which is exactly what the sibling ig_reply_comment does. It names the resource but never states a list/retrieve action, so an agent must fall back to the name to disambiguate from a write tool.

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?

No guidance on when to use this versus ig_list_comments (top-level comments) or ig_reply_comment (posting a reply). There are no conditions, prerequisites, or exclusions stated; the agent is left to infer usage entirely from the tool name.

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

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

Annotations already declare this a safe, idempotent read (readOnlyHint=true, destructiveHint=false, idempotentHint=true). The description adds genuine context beyond them: results are limited to the connected account and the data window is 24 hours, which tells the agent that empty results may mean expiration rather than absence.

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?

A single sentence that front-loads the key fact (live stories of the connected account) and uses the parenthetical only for the non-obvious 24-hour constraint. Nothing is wasted.

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 zero-parameter read tool with full annotation coverage and no output schema, the description covers scope, source account, and data freshness — the main things an agent needs. It stops short of noting the absence of pagination or what an empty response implies, but no significant gap remains.

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 tool takes no parameters, so the baseline is 4. The description correctly implies the call is unscoped by arguments — it always returns the connected account's live stories — and adds nothing misleading about inputs.

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 names a specific resource (stories) and a clear scope (currently live, connected account), which lets an agent distinguish it from media/comment/messaging siblings. The verb is left implicit, carried by the name and title rather than the description text, which keeps it just short of a 5.

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?

Usage is implied rather than stated: an agent can infer it should call this to fetch active stories, and no sibling competes for that job. However, there is no explicit when-to-use, no note on what to do for expired stories, and no mention of alternatives such as ig_list_media for archived content.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, covering the safety profile. The description adds no behavioral context beyond that: no note on pagination behavior, rate limits, result ordering, or how tagging is discovered. It merely restates the resource scope.

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?

A single tight sentence with no filler, and the distinguishing detail ('from other accounts') is front-loaded. It is appropriately sized for a simple list endpoint, though it is a noun phrase rather than an action statement.

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-only list tool with full schema coverage and annotations carrying the safety profile, the description is minimally adequate. It omits any mention of pagination flow (using next_cursor/after), and there is no output schema, so the agent learns nothing about the response shape or ordering.

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 100%, with 'after' documented as a cursor from next_cursor and 'limit' documented with bounds and default. The description adds no parameter meaning, so the baseline 3 applies since the schema does all the work.

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 states a specific resource and scope: media from other accounts where the connected account is tagged. This implicitly separates it from the sibling ig_list_media (the account's own media), though it never names that sibling explicitly. An agent can identify what data is returned without opening the schema.

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?

There is no when-to-use guidance, no prerequisites (e.g., permissions), and no named alternative. With ig_list_media, ig_get_media, and ig_list_stories sitting as siblings, the description does nothing to route the agent among them. The implicit contrast with 'other accounts' media is the only signal, which is not enough.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds genuinely non-obvious behavior: a default metric set applies when `metrics` is omitted, and defaults vary by media type (FEED/REELS/STORY), plus the connected-account scope restriction.

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?

Three short sentences with the primary concept front-loaded and no filler. The parenthetical '(FEED / REELS / STORY)' slightly muddles media types with metric sets, but overall it is tight and efficient.

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 read-only, 2-parameter metrics tool the core behavior is covered: scope, defaults, and media-type variance. Without an output schema the description could reasonably note the return shape, and it omits the vocabulary of valid metric strings, leaving a gap an agent would hit when specifying custom metrics.

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. It explains the `metrics` parameter's optionality and default fallback well, but `media_id` is never described (though its numeric pattern is self-evident) and no valid metric names are enumerated, despite FEED/REELS/STORY being referenced.

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 names a specific resource (one post, reel or story) and the operation (retrieve metrics), which an agent can distinguish from account-level siblings like ig_account_insights. It stops short of explicitly naming the account-level alternative, but the scope ('one post') is clear.

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 useful context — 'Only media of the connected account is supported' — and explains the no-metrics fallback, which implies when calling without metrics is appropriate. However it never states when to prefer this over ig_account_insights or ig_get_media, leaving the sibling choice to inference.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and openWorldHint=true, and the description adds genuinely non-derivable facts: the daily-limit accounting, the env-var write gate, and the pending-container_id return that requires a follow-up call. It doesn't discuss idempotency directly (whether re-calling with the same container_ids republishes or completes the original), which is the main remaining unknown for a non-idempotent mutation.

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?

Three dense sentences, front-loaded with what the tool does, then the limit accounting, then the failure/retry behavior. No filler and no repetition of the title.

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 3-parameter write tool with no output schema, it covers the write gate, the limit cost, and the non-happy-path return shape. It doesn't say what a successful publish returns (media id), which would be the last piece an agent needs to chain a follow-up call, but nothing required to invoke it correctly 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 67%, and the description compensates for the hardest part: it explains that items accepts image and/or video entries and that a returned child container_id can be fed back in as an item, which the schema only hints at via a pattern constraint. It adds nothing for caption, and wait_seconds is only defined in the schema, but the ambiguous parameter is well covered.

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 and resource ('Publishes a carousel of 2–10 images and/or videos') with the distinctive scope markers an agent needs to tell it apart from ig_publish_image, ig_publish_reel, ig_publish_story and ig_publish_container. The multi-item carousel constraint is explicit and unambiguous.

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 operating context: counts as one post against the daily limit, requires IG_ENABLE_WRITES=true, and the exact retry path when videos are still processing. It stops short of naming the single-item siblings as the alternative for non-carousel posts, so the choice between them is left implicit in the tool name.

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

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

Annotations already signal a non-read-only, non-idempotent, open-world write. The description adds genuine value beyond them by disclosing the IG_ENABLE_WRITES=true gating requirement, which is not visible in the annotations or schema. It omits what happens on failure or whether the container must be re-polled.

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?

Two short sentences, front-loaded with the action and the pending-container precondition; every clause earns its place with no repetition of the title.

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 write tool with annotations covering the safety profile and no output schema, the description supplies the essential context (what it consumes, the write gate). Minor gaps remain around polling/retry behavior, but nothing critical for correct invocation 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 coverage is 50%: wait_seconds is fully documented in the schema, while container_id carries no schema description. The description contextualizes container_id as 'a container returned as pending' but adds no format or usage nuance beyond that, so the schema does most of the work.

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 (publish) and resource (container) and adds the crucial qualifier that it acts on a container 'returned as pending by an ig_publish_* tool', which distinguishes it from the several one-shot ig_publish_image/reel/story/carousel siblings. It stops short of explicitly naming the status-check sibling it is adjacent to.

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?

Tells the agent when to use it: after an ig_publish_* tool returns a pending container, and states a hard prerequisite (IG_ENABLE_WRITES=true). No explicit when-not case or named alternative such as ig_get_container_status is given, so it falls short of full routing guidance.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, idempotentHint=false, openWorldHint=true), so the safety bar is largely covered. The description adds a genuine non-structured behavior: the IG_ENABLE_WRITES environment gate that must be satisfied before any call succeeds. It omits other operational traits such as publish rate limits (see sibling ig_publishing_limit) and the asynchronous container-processing flow.

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?

Two short sentences, zero filler, with the capability statement front-loaded and the blocking precondition immediately after. Every clause carries information an agent needs.

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?

No output schema exists, so the description could carry more, yet it never explains the return behavior (the pending container_id referenced only inside the wait_seconds schema text) or how this relates to ig_publish_container / ig_get_container_status. For a write tool with a container-based async pipeline and a sibling rate-limit tool, this is adequate but leaves notable gaps.

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 100%, so all four parameters (image_url, caption, alt_text, wait_seconds) are already documented in the schema with types, bounds and formats. The description adds no syntax, format or default information beyond that, so the baseline 3 applies.

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 (publishes) and resource (single-image feed post) with a binding constraint (public JPEG URL). The 'single-image feed post' scoping implicitly separates it from the sibling publish tools (ig_publish_reel, ig_publish_story, ig_publish_carousel) without the agent needing to open a schema.

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 a hard precondition (IG_ENABLE_WRITES=true) and an implicit content-type constraint via 'single-image feed post', which is real routing value. However, it never names an alternative or states when-not-to-use it (e.g. multiple images → ig_publish_carousel), so usage remains implied rather than explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful domain semantics the annotations cannot express: the rolling 24-hour window, the numeric cap, and the carousel accounting rule. It stops short of saying what happens at the limit or whether the count is account-wide or app-wide.

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?

One sentence that front-loads the measurement, then qualifies it with the two rules that matter (limit and carousel counting). No filler.

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 no-parameter read with no output schema, the description supplies enough to interpret the result: it is a count, scoped to the last 24 hours, against a limit of 100. It could note the response shape (a number vs. an object with limit/remaining), but the gap is minor.

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 tool takes zero parameters, so the schema has nothing to document and the baseline of 4 applies. The description correctly adds no parameter noise.

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 measurement: the count of posts published via the API in the last 24 hours, including the 100-post cap and the carousel-counts-as-one rule. This is clearly a quota-read tool, easily distinguished from the ig_publish_* siblings that consume that quota.

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?

Usage is only implied: mentioning the 100-post limit and 24-hour window suggests checking before publishing, but the description never says when to call it, whether it is a pre-publish check, or what to do if the limit is reached. No alternative tool is named.

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

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

Annotations already declare the write/openWorld/non-idempotent profile, so the description's added value is the async behavior: processing can take minutes and may return a pending container instead of a published reel. The env-flag requirement is also honest operational context. It stops short of noting rate limits (a sibling, ig_publishing_limit, hints they exist) or what a successful call returns.

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?

Three short sentences, front-loaded with what it does, followed by the timing caveat and the prerequisite. Every sentence carries distinct information; nothing is padded.

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 mutation tool with no output schema, the description covers the key unknown an agent faces: the call may not complete synchronously and hands off to ig_publish_container. It is nearly complete, though it omits what a successful publish returns and any mention of publishing quota limits.

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 100%, so the schema already documents all six parameters with types, defaults, and bounds. The description only restates wait_seconds' role in prose without adding format or edge-case detail beyond the schema, so the baseline 3 applies.

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 plus resource ('Publishes a reel') and the input source ('from a public video URL'). This cleanly separates it from ig_publish_image, ig_publish_story, and ig_publish_carousel, which share the same verb but differ in resource.

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?

Names the prerequisite flag (IG_ENABLE_WRITES=true) and the follow-up path when processing is slow (pending container_id goes to ig_publish_container). It gives clear context for use but never states when NOT to use it or how it relates to ig_publish_carousel/ig_publish_story beyond the media type.

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

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

Annotations already declare non-read-only, non-idempotent, open-world behavior, so the bar is lower; the description still adds real context by disclosing the IG_ENABLE_WRITES=true gate and the caption limitation. It omits rates/quotas (a ig_publishing_limit sibling exists) and the async publish-then-poll workflow, keeping it short of a 5.

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?

Three short sentences, zero padding, with the core action, the input constraint, and the enabling prerequisite in descending order of importance. Nothing here is redundant enough to cut.

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 zero-required-parameter publish tool with no output schema, the description covers what to pass, the media-type restriction, and the environment prerequisite. It leaves out the publishing-limit/rate context and the fact that the call may return a pending container requiring a follow-up status check, but those are minor relative to the schema's wait_seconds documentation.

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 100%, so all three parameters are already fully documented in the schema, including wait_seconds semantics and URL formats. The description only echoes the image/video URL distinction without adding format or interaction detail, so the baseline 3 applies.

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 and resource ('Publishes a story') and constrains the input to a public JPEG image or MP4/MOV video URL, which separates it from ig_publish_image/ig_publish_reel by media type and target surface. It never names those siblings explicitly, so differentiation is inferable rather than stated.

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 supplies two useful conditions ('Captions are not supported on stories', 'Requires IG_ENABLE_WRITES=true'), which act as prerequisites/caveats. However it never states when to choose this over ig_publish_image, ig_publish_reel or ig_publish_carousel, nor what to do after publishing (e.g. poll ig_get_container_status), so usage is only implied.

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

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

Annotations only declare it is a non-readonly, non-idempotent, open-world operation; the description goes further by disclosing the persistence side effect (new token written to IG_TOKEN_CACHE_PATH) and the consequence of omitting it (token survives only until restart). It stops short of describing error behavior or rate limits on the refresh endpoint.

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?

Two tightly packed sentences with no filler; the effect (60-day extension) leads, the precondition is parenthesized inline, and the persistence caveat follows. Every clause carries information an agent needs.

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 zero-parameter mutation with no output schema, the description covers the effect, the precondition, and the caching side effect, which is nearly everything needed to call it correctly. It omits what the call returns or how failures surface, which is the only remaining gap.

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 tool takes zero parameters, so the baseline is 4 and there is no parameter meaning for the description to add or obscure. The 100% schema coverage is trivial given the empty object schema.

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 (refreshes) and resource (long-lived access token) plus the concrete effect (extends it another 60 days). This is clearly distinguishable from the sibling ig_token_status, which reports state rather than renewing it.

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 an explicit precondition for use: the token must be at least 24 hours old and not expired. It does not name ig_token_status as the alternative for merely inspecting token validity, so the routing guidance is implied rather than stated.

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

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

Annotations already declare a non-read-only, non-idempotent, open-world write, so the safety profile is covered. The description adds two genuinely useful facts beyond them: the reply is publicly visible and writes must be enabled via IG_ENABLE_WRITES. It says nothing about rate limits, moderation, or failure behavior.

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?

Two short sentences, action first, prerequisite second, with no filler. Every clause carries information an agent needs.

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 mutation with annotations and no output schema, the description covers the key facts (public write, writes flag) but leaves the undocumented comment_id parameter and post-call behavior unexplained. Adequate but with clear gaps.

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 only 50% – comment_id has no description and only a numeric pattern – and the description compensates with nothing about either parameter. It neither explains the ID format/ownership nor clarifies message constraints beyond what the schema already states.

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 (posts) and resource (a public reply to a comment), which is clearly distinct from ig_comment_on_media's top-level commenting action. It does not, however, explicitly contrast itself with the closest siblings such as ig_comment_on_media or ig_list_replies.

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 supplies a real precondition ('Requires IG_ENABLE_WRITES=true'), which tells the agent when the call will be permitted. It gives no guidance on choosing this tool over alternatives like ig_comment_on_media, so usage is only implied by the name and the gating flag.

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

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

Adds substantial behavior beyond the annotations: the 24-hour messaging window, the single-image limit, the one-private-reply-per-comment rule, and the IG_ENABLE_WRITES=true write gate. Annotations only cover the generic readOnly/idempotent/openWorld profile, so the description carries real operational context.

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?

Three tightly packed sentences, front-loaded with the core action and followed by constraints and the alternate mode. No filler 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?

For a write tool with no output schema, it covers the key operational constraints (time window, media limit, write flag, private-reply semantics). It omits error/response behavior and does not spell out what happens if both text and image_url are provided.

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 75%, and the description adds meaning on top: text and image_url are alternatives ('text or one image'), and recipient_comment_id is framed as an alternative path to recipient_id that triggers a private reply. It doesn't state that no parameters are required or clarify failure when neither text nor image 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?

States a specific verb+resource ('Sends a DM') and enumerates the two supported payloads (text or one image), plus a distinct private-reply mode. It does not name a sibling tool, so differentiation from ig_reply_comment and ig_get_messages is only implicit.

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 concrete usage conditions: only within 24 hours of the recipient's last message, one image maximum, and recipient_comment_id for private replies (one per comment). It never explicitly says when to prefer a different sibling tool, but the routing between the two modes is clear.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the meaningful operational prerequisite that writes must be enabled via IG_ENABLE_WRITES=true, which annotations cannot express.

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?

Two short sentences, zero filler, with the core action stated first and the prerequisite second. Nothing needs trimming and the important constraint is easy to spot.

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 mutation with annotations covering safety and no output schema, the description covers purpose and the write-gate prerequisite. It omits whether disabling hides or deletes existing comments and what happens on failure, leaving some behavioral gaps for an agent.

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% for both required parameters. The description alludes to 'posts' and 'comments' but does not explain that media_id is the numeric post identifier or clarify the boolean semantics of enabled; the schema pattern is the only documentation of media_id format.

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 (turns on/off) and resource (comments on one of the account's posts), which is a clear, self-contained purpose. It does not explicitly name how it differs from siblings like ig_hide_comment (per-comment moderation) or ig_list_comments, but the post-level scope is inferable.

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 a hard prerequisite (IG_ENABLE_WRITES=true), which is genuinely useful gating information. However, it offers no guidance on when to prefer this tool over ig_hide_comment or other comment-management siblings, so usage is only implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered structurally. The description adds useful context beyond that: it discloses the specific facts returned (account identity, token origin, expiry 'when known') and the write-enablement flag, which an agent could not infer from annotations alone.

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?

Two tight sentences with no filler; the core action comes first and the secondary reporting detail follows. Every clause adds information an agent can act on.

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?

With no output schema, the description carries the burden of describing results and does so reasonably well by listing the four reported facts. It stops short of any return format, field names, or behavior when no token is configured, leaving a minor gap for a zero-param status tool.

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 tool takes zero parameters, so per the baseline there is nothing for the description to disambiguate. No parameter-level explanation is needed or missing.

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 states a specific verb ('Checks') and resource ('the configured access token') and enumerates what is reported: owning account, source (env vs refreshed cache), and expiry. It is naturally distinguishable from the mutating sibling ig_refresh_token, though it never names that sibling, so sibling differentiation is implicit rather than explicit.

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?

Usage is only implied: an agent can infer this is a diagnostic/introspection call to run before write operations or when expiry is a concern. There is no explicit when-to-use, when-not-to-use, or pointer to ig_refresh_token as the action to take when the status is bad.

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