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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write/safety profile is partly known. The description adds genuinely useful behavior: the default is a dry-run preview and the write only occurs under an explicit flag or env var, which is not derivable from 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?

Two tight sentences, zero padding. The endpoint and the safe-default behavior are front-loaded so the agent sees the critical constraint immediately.

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 4-param mutation tool with full schema coverage and no output schema, the description covers what it does and the preview/apply gate. It leaves out what the preview response contains, but nothing essential 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 description coverage is 100%, so the schema already documents apply, account, mediaId, and message. The description restates the apply semantics and adds the IG_WRITE_MODE fallback, but adds little on the other three parameters; 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 ('Post') and resource ('a new top-level comment on a media object'), and even includes the underlying endpoint. The word 'top-level' explicitly separates it from instagram_reply_to_comment, so an agent can route correctly.

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: the tool previews by default and requires apply:true (or IG_WRITE_MODE=apply) to actually write. It does not explicitly name the sibling alternative (reply_to_comment) or state exclusions, so it falls short of a 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 readOnlyHint=false, idempotentHint=false and destructiveHint=false, but the description adds non-obvious behavior annotations cannot express: this call does NOT publish, ingestion is asynchronous (must poll to FINISHED), and the server never downloads the URL so media format/size/duration validation is deferred to Instagram on fetch. That deferred-validation and two-phase nature is the key operational trait an agent must know.

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 tight sentences, front-loaded with the phase-1 framing and the workflow routing, with no filler. The final clause on validation is dense but earns its place; only the media_type restatement feels slightly duplicative of the schema.

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 13-parameter, non-idempotent write tool with no output schema, the description covers everything an agent needs: the preconditions (public HTTPS URL), the post-call sequence, the return value ('the returned container id'), and where validation actually happens. Nothing material 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?

With 100% schema description coverage, the baseline is 3 and the schema already documents all 13 parameters. The description adds real semantic value by explaining that only URL form and caption limits are enforced client-side (format/size/duration are not), and it reinforces the media_type omission rule — though that rule is already repeated in the schema, so the gain is marginal rather than transformative.

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 (create a media container) and frames it precisely as 'Phase 1 of publishing', explicitly contrasting it with the actual publish step. It names the two sibling tools that complete the workflow (instagram_get_container_status, instagram_publish_media), so an agent can distinguish it from instagram_publish_media or the instagram_post_* convenience wrappers without opening 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?

Gives an explicit ordered workflow: create container, poll instagram_get_container_status until FINISHED, then call instagram_publish_media with the returned container id. It also states a concrete conditional for a parameter decision ('Omit media_type for a single feed image; set REELS/STORIES/CAROUSEL otherwise'), which is exactly the when-to-use guidance an agent needs.

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 readOnlyHint=false, but the description adds materially new behavior: the double gate on apply:true and the IG_ALLOW_DESTRUCTIVE environment flag, plus the fact that a failed gate degrades to a preview rather than erroring. It does not describe the return payload, but the irreversibility and gating disclosure are the important traits here.

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 compact sentences, each doing distinct work: what it does, the irreversibility plus safer alternative, then the gating rule. Irreversibility is front-loaded and no sentence is 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 destructive mutation with no output schema, the description covers the safety profile, the alternative, and the exact conditions under which the write fires versus previews. Nothing needed to invoke it safely 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 100%, so commentId and account are already documented. The description still adds meaning beyond the schema by tying apply:true to a second, external precondition (IG_ALLOW_DESTRUCTIVE=true), which the schema's description of apply does not mention.

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 ('Permanently delete a comment'), includes the underlying endpoint, and explicitly distinguishes itself from the moderation-friendly sibling instagram_hide_comment. An agent can route between delete, hide, and unhide without opening any 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 an explicit when/when-not: prefer instagram_hide_comment when the moderation may need to be undone, otherwise this tool. It also states the runtime preconditions (apply:true plus IG_ALLOW_DESTRUCTIVE=true) that must hold before anything actually happens.

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 and openWorldHint, but the description goes further: it names the underlying endpoint (GET /{ig-id}), discloses that hidden/omitted fields are silently absent rather than null or errored, and warns that several returned fields are untrusted free text wrapped in a content fence — a genuinely useful safety disclosure 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?

Three tight sentences: the returned-field list front-loads the payload, followed by the read-only endpoint and then the caveats. 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?

With a full input schema, an output schema, and read-only/open-world annotations already in place, the description covers the remaining gaps an agent needs — scope of the account, absent-field behavior, and the untrusted-content framing. Nothing material 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?

There is a single optional parameter and the schema describes it fully (100% coverage), including the multi-account semantics and the IG_ACTIVE_PROFILE default. The description adds nothing about the account parameter, 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 (Fetch) and resource (profile of the operated Instagram professional account) and enumerates the exact returned fields, which cleanly separates it from analytics siblings like instagram_get_account_insights or instagram_get_audience_demographics.

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 'of the operated Instagram professional account' implies the scope, but there is no explicit when-to-use guidance and no named alternative for the adjacent questions an agent might have (e.g. follower counts over time → instagram_get_account_insights). Usage is inferable 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?

Adds substantial context beyond the readOnly/openWorld annotations: the 90-day retention bound, the critical 'absent, not zero' semantics for missing metrics, the missingMetrics/notes reporting, and that credentials are stripped from paging URLs. This is exactly the operational detail an agent needs to interpret results correctly.

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 dense sentences that are front-loaded with the resource and endpoint, then layer defaults, retention, and output semantics. Every sentence carries information, though the density is near the upper end of comfortable reading.

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 annotations covering the safety profile and an output schema present, the definition still supplies the non-obvious behavioral facts (retention, missing metric semantics, credential stripping). Nothing needed to call or interpret the tool 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 100%, so the schema already documents each parameter in detail (retention clamping, enum sets, defaults). The description reinforces the metric-set and retention constraints but adds little syntax or meaning beyond what the schema provides, matching the baseline 3.

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 ('Account-level insights') with the underlying endpoint, and the 'account-level' scope implicitly separates it from the media-level sibling instagram_get_media_insights. It does not explicitly name any alternative, so it falls short of the 5-level sibling differentiation.

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?

Mentions the post-2025 views-centric metric set and the 'aggregated totals by default' behavior, which implies when the tool is appropriate, but gives no explicit when-to-use/when-not guidance or alternative routing (e.g. versus demographics or online-followers tools). Usage 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?

Beyond the readOnlyHint/openWorldHint annotations, it discloses the 100-follower threshold, that Meta returns an error naming that rule, and the crucial data semantics that an empty metric appears in missingMetrics with a note and is absent rather than zero. This is exactly the behavioral context an agent needs to interpret results correctly.

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?

Purpose is front-loaded, followed by prerequisites and then the output nuance, in three tight sentences with no padding. The inline endpoint/metric_type parenthetical is slightly technical but earns its place by pinning the exact call.

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?

Given rich annotations and schema coverage plus an output schema, the description still adds the non-obvious pieces an agent needs: the follower threshold, its error behavior, and the missing-vs-zero semantics. Nothing required to call or interpret the tool is absent.

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 the schema already documents account, metrics, breakdown, and timeframe with enums and defaults. The description restates the timeframe requirement already in the schema and adds no new syntax or format detail about the parameters themselves, 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 (get) and resource (follower/engaged-audience demographics) for the operated account, and anchors it to the exact API endpoint. This clearly separates it from sibling insight tools, but it never names an alternative tool to route against, so it stops 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?

Provides concrete prerequisites (a timeframe is required, account needs 100+ followers) and even the failure mode when the threshold is not met. It gives clear context for when the call is valid but offers no explicit when-not or alternative-tool steering.

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?

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses that text and usernames are fenced untrusted data, that undisclosed fields are omitted rather than nulled, that a deleted comment errors, and that replies are truncated (repliesTruncated) or dropped without an id (omittedWithoutId plus note). That is exactly the kind of edge-case behavior an agent needs.

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 purpose in the first clause, then layers edge cases efficiently; every sentence carries information. It is dense and reads as a single long paragraph rather than being broken up, which slightly hurts scannability.

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 an output schema present, the description needn't restate field shapes, yet it covers the return semantics that matter (truncation, omission, untrusted text, error on deleted comment) and the account-selection model is handled by the schema. Nothing needed to call 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 100%, so both parameters (commentId, account) are already documented in the schema and the baseline is 3. The description adds no additional meaning about the parameters themselves.

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 ('Fetch a single comment by id') plus the scope of what comes back (moderation state, parent/media context, inline replies). It is clearly distinguishable from siblings like instagram_list_comments or instagram_get_media.

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 'by id' framing and the schema's hint that the id comes from instagram_list_comments imply the use case, but the description never explicitly says when to prefer this over listing comments or how it relates to instagram_reply_to_comment / instagram_hide_comment. Usage is inferable 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 readOnlyHint=true and openWorldHint=true, and the description's 'Read-only.' merely restates that. However, it adds genuine behavioral value beyond annotations: the container state machine, the anti-pattern (do not re-create while IN_PROGRESS), and the recovery path for ERROR/EXPIRED.

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 compact sentences, zero filler, with the core purpose front-loaded and the state-handling rules packed into the second sentence. Nothing can be removed without losing routing 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 an output schema present, the description needn't explain the return payload, yet it usefully names the status_code values an agent must branch on. Combined with 100% schema coverage and clarifying annotations, nothing needed to call this tool 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 100% (both account and containerId are documented, including that containerId is the creation_id from instagram_create_media_container), so the schema carries parameter meaning. The description adds no syntax or format detail beyond that, making 3 the correct baseline.

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 (Read) and resource (media container's processing state) and enumerates the exact status values returned (IN_PROGRESS, FINISHED, ERROR, EXPIRED, PUBLISHED). An agent can immediately distinguish this polling/status tool from the sibling that creates containers or the one that publishes media.

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 explicit conditional routing: publish only when FINISHED, keep polling on IN_PROGRESS without re-creating, and re-create on ERROR/EXPIRED. This is actionable when-to-do-what guidance rather than mere context, and it steers the agent's next tool call.

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 cover the safety profile (readOnlyHint, openWorldHint); the description carries the real behavioral load. It discloses that captions are fenced untrusted text, that undisclosed fields are omitted rather than nulled, that deleted objects and expired stories error out, and how carousel children lacking ids are counted and how partial album failures degrade gracefully — far more than the annotations provide.

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 dense sentences, front-loaded with the core fetch action before edge cases. Every sentence carries distinct information (children, caption trust, omission/error semantics, partial failure), though the edge-case list is tightly packed and could be structured as a short list for faster scanning.

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 less prose, yet the description still explains the important return-shape quirks (children, omittedWithoutId, note on partial failures). For a read-only, open-world fetch with 100% schema coverage, nothing an agent needs to call 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 100% and both parameters (account, mediaId) are fully documented in the schema, including the id pattern and default profile behavior. The description adds little parameter-level detail beyond the implicit use of the id, 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 ('Fetch a single media object by id'), which cleanly distinguishes it from the sibling instagram_list_media. It also defines the shape of what is fetched (carousel children under `children`), so an agent knows exactly what the call returns 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?

Usage is only implied: the tool fetches one object by id, and the schema description notes the id comes from instagram_list_media. The description itself never states when to prefer this over instagram_list_media or instagram_list_stories, nor any prerequisite (e.g. account selection) — minimal but inferable 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 only declare readOnlyHint and openWorldHint, so the description carries the operational caveats: empty/error returns for legacy media and expired stories, and the key semantic rule that a metric Instagram has no data for appears in missingMetrics and is absent rather than zero. That 'absent, not zero' distinction is genuinely non-obvious and valuable, though it partly describes the output schema.

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 dense sentences, front-loaded with the resource and endpoint, then caveats. Every sentence carries information, though the metric-validity point mildly overlaps the schema descriptions.

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 an output schema present, the description need not explain return shape, and it appropriately focuses on the non-obvious behaviors (missingMetrics semantics, error cases, media_product_type hint). It is complete enough to call correctly; only the missing when-to-use-vs-siblings guidance keeps it from a 5.

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 every parameter is already documented in detail, and this description largely restates the media_product_type behavior that the schema already explains. Baseline 3 applies: the description adds no metric syntax, default-set enumeration, or account-profile nuance beyond what the structured field provides.

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 ('Insights for a single media object') and even pins the endpoint, so the agent knows it fetches metrics rather than metadata. The 'single media object' scope implicitly separates it from instagram_get_account_insights and instagram_get_audience_demographics, but no sibling is named explicitly as the HIGH calibration example does, so it stops 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?

It gives useful preconditions (supply media_product_type so invalid metric/type combinations are rejected before the call is spent) and edge-case contexts (pre-professional media, expired stories). However it never states when to reach for this tool versus instagram_get_media or instagram_get_account_insights, nor any required permissions, leaving the routing decision inferred.

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?

Goes well beyond the readOnlyHint/openWorldHint annotations: discloses the 30-day data window, flags that the metric is on a deprecation watch-list and may return a 'metric no longer available' error, and explains the missingMetrics/note fallback shape instead of an empty list. That is exactly the kind of failure-mode and scope context an agent cannot get from 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?

Three sentences, front-loaded with what the tool returns before caveats. The inline endpoint path is mildly redundant but functions as a precise metric identifier; no filler otherwise.

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-shape explanation is not required; the description still covers the two things the schema cannot — the 30-day data horizon and the deprecation/error behavior. Nothing an agent needs to call this 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 coverage is 100% and the single 'account' parameter is fully documented in the schema (multi-account profile selection, default fallback). The description adds nothing about parameters; baseline 3 is appropriate when the schema carries the semantics.

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: hourly distribution of when the account's followers are online, and anchors it to the exact insights metric (online_followers, period=lifetime). This is specific enough that an agent can distinguish it from the broader instagram_get_account_insights or instagram_get_audience_demographics without opening 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?

Usage is implied by the metric definition but there is no explicit when-to-use guidance and no named alternative (e.g., use instagram_get_account_insights for aggregate reach/impressions). The deprecation warning tells the agent when the tool may fail, which is useful, but not when to prefer a sibling.

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 cover readOnly/openWorld, yet the description discloses real behavioral traits: a carousel counts as one post, quota_total is read live and never hardcoded, remaining is derived only when the total is known, and — critically — a no-usage response causes a failure rather than a misleading 0. That failure-mode disclosure is exactly the kind of context annotations cannot carry.

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, front-loaded with the tool's purpose before the field semantics, with zero filler. The parenthetical about carousel counting and the never-hardcoded note each carry distinct operational value.

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?

Despite a simple schema and an existing output schema, the description still supplies the semantic meaning of each quota field plus the edge-case failure behavior. Nothing an agent needs to interpret or trust the result 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?

Only one parameter, and the schema already documents it at 100% coverage (multi-account default behavior is spelled out in the property description). The description adds nothing about the account parameter, 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?

Specific verb ('Report') and resource ('the account's content-publishing usage against its rolling-window quota'), which no sibling covers — the neighboring tools publish, list, or read insights, not quota consumption. An agent can select this 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?

Implied usage is clear enough from the quota framing (check before publishing via instagram_publish_media / instagram_post_*), but the description never states when to call it, nor names any alternative or prerequisite. The guidance must be inferred rather than read.

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 idempotentHint=true, destructiveHint=false and readOnlyHint=false, but the description goes further by explaining the idempotency semantics and — critically — the non-obvious edge case that a media owner's own comment on their own media stays visible while the API still returns success. That is a real behavioral gotcha no annotation or schema conveys.

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 verb+resource and the endpoint, then ordered by importance: reversibility, idempotency, edge case, invocation workflow. It is dense and the parenthetical endpoint template is slightly noisy, but very little of it is 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 3-parameter mutation with no output schema, the description covers the safety profile, the surprising edge case, and the preview gate. It does not say what the preview result actually contains, which is the one remaining gap for an agent deciding how to interpret a dry run.

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 the baseline is 3. The description adds context beyond the schema by explaining the preview-by-default workflow and the IG_WRITE_MODE=apply environment alternative, which is not expressible in the apply parameter's own description.

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 ('Hide a comment'), even pinning the underlying endpoint, which makes it unmistakably distinct from instagram_delete_comment, instagram_unhide_comment, and instagram_get_comment. The sibling set is large and this tool's scope is immediately legible without opening any 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?

Explicitly positions the tool as 'reversible moderation, preferred over delete', which names the alternative (instagram_delete_comment) and the condition that selects this one. The preview/apply gate is also stated up front so the agent knows a dry-run happens unless it opts in.

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?

With readOnlyHint/openWorldHint already covering the safety profile, the description still adds substantial context: content is fenced untrusted text (explicit prompt-injection warning), repliesTruncated and paging.truncated flags, the IG_MAX_ITEMS cap interaction, and the omittedWithoutId accounting for id-less comments. That is behavior an agent could not derive from annotations or schema.

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 core purpose, then pagination, then output caveats and the untrusted-text warning. It is a single dense paragraph where every sentence carries information, though the trailing omittedWithoutId sentence is niche enough to be slightly expendable.

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 mechanics need not be re-explained, yet the description covers the two things an agent most needs and cannot get elsewhere: how pagination/truncation signals behave and that comment text must be treated as untrusted data. Nothing needed 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 100%, so the baseline is 3. The description goes beyond the schema by tying fetchAll to the server-side IG_MAX_ITEMS cap and to paging.truncated, clarifying that limit is only a page-size hint and independent of the cap — meaningful semantics that the field docs alone do not fully spell out.

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 precise verb+resource with scope qualifiers: 'top-level comments on a media object', plus ordering ('newest first') and reply expansion. It implicitly separates itself from instagram_get_comment (single comment) and the write siblings, but never names an alternative, so it falls short of the explicit sibling differentiation a 5 requires.

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 fetchAll sentence gives real guidance on when to aggregate rather than fetch one page, which is usage-level direction. However, nothing tells the agent when to reach for this tool instead of instagram_get_comment or how it relates to the comment-write siblings; the routing 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?

With readOnlyHint/openWorldHint already covering the safety profile, the description adds substantial behavioral context: newest-first ordering, cursor pagination defaults, server-cap truncation semantics, untrusted fenced caption text, fields that may be absent, and accounting for items Instagram returns without an id (omittedWithoutId). This is far beyond what annotations convey.

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 purpose and the stories exclusion, then pagination, then data-integrity caveats; every sentence carries distinct, non-redundant information. It is on the long side, but no sentence is 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?

Output schema exists so return values need little prose, yet the description still explains the two result flags an agent must interpret (paging.truncated, omittedWithoutId plus note). Nothing needed to call or interpret the tool 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 coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning: limit is only a page-size hint and is explicitly independent of the server item cap that bounds fetchAll, and fetchAll is tied to the paging.truncated outcome. That is real added value over the per-field schema text.

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 (list the operated account's own media: feed posts, reels, albums), names the scope boundary (own, not tagged), and explicitly distinguishes itself from instagram_list_stories. An agent can select it without opening any 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?

Explicitly routes the story case to instagram_list_stories and warns that an empty page says nothing about active stories, which is exactly the misuse it prevents. It also states when to use fetchAll vs the default single page and what the tradeoff is (server item cap, paging.truncated).

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?

Far exceeds the readOnlyHint/openWorldHint annotations: it discloses the 24h expiry rule, newest-first ordering, cursor pagination, the IG_MAX_ITEMS server cap and the paging.truncated flag under fetchAll, that captions are fenced untrusted text, that stories lack like_count/comments_count, that media_url may be withheld, and that id-less items are dropped with omittedWithoutId/note counts. This is exactly the operational context the annotations cannot carry.

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?

Purpose and scope are front-loaded in the opening clause, and each following sentence carries distinct information (expiry interpretation, fetchAll/truncation, untrusted captions, field absences, omitted items). The middle sentences are dense and slightly list-like, which costs a point versus a crisper layout, but nothing 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?

With an output schema present the description need not explain return values, yet it still covers the quirks an agent must reason about: expiry semantics, pagination/truncation, withheld fields, and dropped items. For a 4-param read with an output schema, nothing material 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 100%, so the schema already documents after, limit, account and fetchAll, including their bounds and defaults. The description restates the fetchAll/limit distinction and notes a story expiring between pages drops out, but adds little syntax or format meaning beyond what the schema already supplies, so 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+resource ("List the operated account's live stories") and immediately scopes it with the 24-hour window and newest-first ordering. It explicitly routes non-story content to the sibling instagram_list_media, so an agent can separate this tool from its nearest alternatives without opening any 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 explicit when-to-use (live stories only, inside the 24h window), when-not (feed posts, reels, albums belong to instagram_list_media), and how to read the edge case that an empty result means nothing is live now rather than nothing was ever posted. It also names instagram_get_media for expired items, completing the routing picture.

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 cover readOnlyHint and openWorldHint. The description adds genuinely useful behavior beyond them: newest-first ordering, cursor pagination, fenced/untrusted caption and username handling, and the fact that items returned without an id are dropped with an omittedWithoutId count and note. It omits rate-limit or auth expectations, so not 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?

Roughly three dense sentences, front-loaded with the core purpose and scope before edge-case notes. Every sentence carries information, though the parenthetical about Path-B mention discovery is slightly tangential 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?

With an output schema present, the description needn't detail return values, and it instead covers the tricky cases (untrusted text, omitted-without-id accounting). For a read-only paginated list tool this is nearly complete; only auth/rate-limit context is absent.

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 (after, limit, account, fetchAll) are already documented in the schema. The description's mention of cursor pagination corroborates 'after' but adds no syntax or format detail beyond it, 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 ('List media the operated account has been TAGGED IN') and names the exact API edge (/tags). It is clearly distinguishable from sibling list_media and list_stories by scope, and it explicitly rules out the confusion with @mentions.

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 draws a sharp boundary between tags and @mentions, telling the agent this tool cannot serve pull-based mention discovery. That is a real exclusion, but it never names a sibling tool as the alternative for related tasks (e.g., list_media), so it stops just 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?

Goes well beyond the annotations: the write is gated behind an opt-in apply flag with a non-mutating preview default, the poll budget can end in status=in_progress with a resume_container_id, and the duplication hazard of re-creating on resume is called out. It also discloses that format/size/dimension validation happens on Instagram's fetch rather than client-side, which is exactly the kind of non-obvious behavior an agent needs.

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 purpose, then preview behavior, then the resume path — three tight sentences with no filler. Minor redundancy: 'Preview (the default) performs nothing' restates the apply parameter's schema text and is slightly awkwardly phrased.

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, so the description carries the return-value burden and does so: it names status=in_progress and resume_container_id, the two fields an agent must branch on. Combined with the thorough schema and annotations, nothing material about 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 100%, so baseline would be 3, but the description adds cross-parameter semantics the schema documents only in isolation: the apply+resumeContainerId combination that finishes an in-progress publish, and the fact that resuming supersedes media inputs. The apply-to-post and resume-to-finish relationship is the key invocation contract and is spelled out.

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 (single feed image or 2–10 image carousel) and describes the full workflow it encapsulates: create container(s), wait, publish. This lets an agent distinguish it from the lower-level siblings instagram_create_media_container / instagram_publish_media and from instagram_post_reel / instagram_post_story by media type.

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 preview-vs-apply default clearly and gives explicit recovery guidance ('re-run with apply:true and resumeContainerId', 'never create a new post, which would duplicate it'), which is genuinely actionable. It stops short of explicitly routing the agent to sibling tools (e.g., which tool to use for reels/stories or when to drop to the container-level primitives), leaving that to name 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 declare the mutation profile (readOnlyHint=false, non-idempotent), and the description adds behavior annotations cannot express: the internal create/poll/publish sequence, that processing can take a while, the in_progress/resume recovery contract, the duplicate-prevention rule, and that media validation happens on Instagram's side, not here.

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?

Dense but front-loaded: the pipeline summary leads, recovery and preview caveats follow, and the trailing validation note is a legitimate boundary statement. Every clause carries information, though the run-on construction asks more parsing effort than ideal.

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 9-parameter, open-world, non-idempotent write with no output schema, the description covers everything an agent needs to call it correctly: the preview/apply gate, the async resume contract, and where validation responsibility lies. Nothing material 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 100%, so all nine parameters are already documented in the schema, including apply, resumeContainerId and videoUrl. The description only reiterates the resume flow, which the schema already covers; baseline 3 is appropriate.

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 ('Publish a reel') and enumerates the exact three-step pipeline (create container, wait for processing, publish) that the single call abstracts. This distinguishes it from the lower-level siblings instagram_create_media_container and instagram_publish_media, which an agent might otherwise reach for.

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 operational guidance for the async path: 'If processing exceeds the poll budget the result is status=in_progress with a resume_container_id — re-run with apply:true and resumeContainerId to finish (never create a new post)'. It also warns 'Preview performs nothing'. It does not, however, explicitly say when to prefer the granular siblings over this convenience tool.

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?

Beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false), the description discloses the async processing model, the poll budget, the in_progress/resume_container_id failure mode, the rule against creating duplicate posts, and the 24-hour story expiry. This is materially more than the annotations provide and covers exactly the behaviors an agent needs to retry safely.

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 tightly packed sentences, front-loaded with the core action and the media constraint before the preview and resume caveats. No filler, and each clause carries operational 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 description carries the burden of describing returns and does cover the important abnormal case (status=in_progress plus resume_container_id). It does not describe the successful publish response shape, which is a minor gap for a write tool with zero required parameters.

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 the schema already documents apply, account, imageUrl, videoUrl, and resumeContainerId in detail. The description largely restates the one-of imageUrl/videoUrl rule and the resume semantics, adding little beyond what the schema says; the baseline of 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?

The description names a specific verb (publish) and resource (photo or video story) and immediately distinguishes itself from siblings by spelling out the composite workflow (create STORIES container, wait, publish) rather than the granular container/publish tools. An agent can tell this apart from instagram_post_image, instagram_post_reel, and instagram_create_media_container without opening any 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 concrete selection rules: exactly one of imageUrl or videoUrl, preview performs nothing unless apply is set, and the resume path (apply:true + resumeContainerId) instead of creating a new post. It does not explicitly contrast with the alternative instagram_create_media_container + instagram_publish_media route for agents needing manual control, so it falls just short of a 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 only say idempotentHint=false; the description converts that into concrete operational consequences (repeated publish costs quota and posts a duplicate, never auto-retried) and specifies the safe retry protocol. This is exactly the behavioral context structured fields cannot convey.

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, zero filler. The pipeline position and precondition come first, the idempotency warning after, which matches the order an agent needs to reason about the call.

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 still names the return value, and it covers the precondition, the safety envelope (nature of non-idempotency) and retry policy. Nothing essential 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 description coverage is 100%, including the apply preview flag, account profile selection and the creationId pattern, so the schema already carries parameter meaning. The description reiterates that creationId must be FINISHED but adds no new syntax or format detail.

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 ('publish a media container that has finished processing') and positions itself in the pipeline as 'Phase 2 of publishing', which cleanly separates it from instagram_create_media_container (phase 1) and instagram_get_container_status. The return value (new media id) is also named.

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?

Explicitly states the precondition ('The container must be FINISHED (see instagram_get_container_status)') and points at the sibling that verifies it. It also gives a when-to-retry rule and the penalty for retrying blindly, so no usage condition 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?

The annotations only declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true; the description adds the critical, non-obvious trait that the call is a no-op preview unless apply:true or IG_WRITE_MODE=apply is set. It does not mention rate limits, idempotency, or whether duplicate replies can be posted, so it is not fully transparent.

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 sentences, zero filler, with the core action and endpoint front-loaded and the preview/apply gating immediately following. Every clause 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?

For a write tool with no output schema, the description covers the main gotcha (silent preview unless apply is set) and the endpoint. It leaves the preview response shape and failure/repeat-call behavior unstated, which is a minor but real 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 3 would be the baseline, but the description adds meaning beyond the schema by documenting the environment-variable alternative (IG_WRITE_MODE=apply) that governs the apply parameter. It says nothing additional about commentId, message, or account.

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 ('Post a threaded reply under an existing comment'), gives the underlying endpoint, and scopes it to threaded replies, which implicitly distinguishes it from instagram_create_comment (top-level comment) and instagram_reply_to_comment's read-side siblings like get_comment.

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?

Clearly explains the operating mode: it previews by default and requires a re-run with apply:true (or IG_WRITE_MODE=apply) to actually post. That is a strong usage condition. It does not explicitly name the sibling tool to use for non-threaded comments, so it stops short of the top score.

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 readOnly, idempotent, destructive, and openWorld hints. The description adds genuinely useful behavioral context beyond that: the idempotent no-op semantics are restated with meaning, and the preview-by-default versus apply:true workflow is disclosed, which the annotations don't convey. It doesn't mention auth requirements 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?

Three compact sentences, each earning its place: purpose, idempotency, and the preview/apply workflow. Front-loaded with the core action, no waste.

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 4-param mutation tool with full schema coverage and no output schema, the description covers the critical operational detail (preview vs apply) that an agent must know. It omits only minor details like response shape or error behavior, which is acceptable given no output schema.

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 four parameters including apply, account, enabled, and mediaId. The description corroborates the apply/IG_WRITE_MODE behavior but adds no syntax or format details beyond what the schema provides, making the baseline 3 appropriate.

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: toggling whether a media object accepts new comments, with the underlying API endpoint. Distinguishes itself from siblings like instagram_hide_comment and instagram_list_comments by scoping to the commenting-enabled flag on a media object.

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 explains the preview/apply mechanism and the IG_WRITE_MODE environment variable, which implies when the tool takes effect. However, it doesn't explicitly say when to use this versus alternatives like hide_comment, leaving the distinction to inference from the 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 readOnlyHint and openWorldHint, and the description meaningfully adds beyond them: Path B uses debug_token for validity/scopes/expiry, while Path A has no introspection endpoint so expiry comes from the recorded IG_TOKEN_EXPIRES_AT and is 'unknown' when absent. That asymmetry is genuinely useful behavior disclosure; only permissions/rate-limit context is missing.

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 one dense paragraph, but the core action is front-loaded and each clause (auth path, expiry source, refresh warning) carries information. The internal-mechanism detail (debug_token, IG_TOKEN_EXPIRES_AT) is slightly more than a selection decision strictly 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?

An output schema exists, so return-shape explanation is not required, and annotations cover the safety profile. Combined with the explicit Path A/B distinctions and unknown-expiry caveat, an agent has everything needed to call this single-optional-parameter tool correctly.

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% and the single 'account' parameter is fully documented in the schema (profile name, default profile fallback). The description adds nothing about the parameter, so 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?

The description opens with a specific verb and resource ('Report the active credential') and enumerates exactly what is reported: auth path (A/B), token presence, account ID, validity, scopes and expiry. No sibling tool does anything comparable, so the read-token-status role is 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?

Usage is only implied: the tool is clearly a diagnostic/status check, and the 'refresh warning as the threshold nears' hints at a proactive use case. However, the description never says when to call it (e.g. before publishing, or when an auth error occurs) and offers no alternatives or 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 readOnly=false, idempotentHint=true, destructiveHint=false, but the description adds the non-obvious dry-run-by-default safety model and the env-var override, which annotations cannot convey. It also restates idempotency in behavioral terms ('unhiding a visible comment leaves it visible'), reinforcing rather than contradicting the annotation.

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: what it does, its idempotent behavior, and how to actually commit the change. The core action is front-loaded and every clause carries 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 description covers action, idempotency, the preview/apply workflow, and the endpoint. It omits what a successful call returns, permission/scope requirements, and error behavior on an invalid or already-deleted comment id, but nothing essential 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 100%, so the schema already documents apply, account, and commentId; baseline would be 3. The description nonetheless adds meaning beyond the schema by documenting the IG_WRITE_MODE=apply environment-variable alternative to the apply flag, plus the hide=false path semantics.

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 ('Unhide a previously hidden comment') and even names the underlying endpoint (POST /{comment-id}?hide=false). This clearly distinguishes it from sibling instagram_hide_comment and instagram_delete_comment 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?

Gives clear operational context: preview by default, re-run with apply:true (or IG_WRITE_MODE=apply) to commit, and notes idempotent behavior. It does not explicitly name alternatives such as hide_comment or delete_comment or state when not to use this tool, so it stops short of a 5.

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