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

Annotations only provide openWorldHint, so the description carries the burden of explaining the mutating behavior. It does this well by disclosing that the tool previews by default and only performs the write when apply:true is set. This is important, non-obvious behavioral context that goes beyond the 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?

The description is two concise sentences with no filler. It front-loads the core action and endpoint, then immediately gives the critical preview/apply instruction that an agent must know before invoking.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple: four params, all schema-documented, no output schema. The description covers the endpoint, the top-level nature of the comment, and the preview/apply behavior, which together are sufficient to call it correctly. It could additionally note that replies belong to instagram_reply_to_comment, but that is a minor omission rather than a correctness 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 description coverage is 100%, so all four parameters are already documented. The description adds the key apply gate semantics and the IG_WRITE_MODE alternative, but it does not add much detail about mediaId or message beyond the schema. 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?

The description states a specific action: 'Post a new top-level comment on a media object' and includes the API endpoint. The phrase 'top-level' clearly distinguishes this from sibling tools like instagram_reply_to_comment, so an agent can select it correctly without inspecting other schemas.

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 clearly explains the preview-by-default behavior and exactly how to perform the write: 're-run with apply:true (or set IG_WRITE_MODE=apply)'. It does not explicitly name alternative tools or when not to use this tool, but the 'top-level' qualifier implies the boundary with reply tools.

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 annotations indicating a write operation, the description discloses key behavior: it does not publish, media validation is deferred to Instagram's fetch, the server never downloads the URL, and only URL/caption limits are checked locally. This prevents an agent from assuming the media is live after container creation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences with no filler. It front-loads the most important distinction ('does NOT publish'), states the workflow, and gives the key media_type rule compactly. Every sentence contributes essential guidance.

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 the tool's complexity (13 parameters, no output schema), the description provides the essential workflow context, names the follow-up tools, clarifies validation behavior, and mentions the returned container id. The remaining details are covered comprehensively by the schema, so nothing critical is missing 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 coverage is 100%, and the schema already documents each parameter in detail. The description adds extra value by clarifying when to omit media_type, emphasizing caption limits, and explaining that URL format is the only client-side media check, which helps the agent reason about parameter constraints beyond the 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?

The description clearly states a specific action ('create a media container'), the resource ('Instagram'), and its role as 'Phase 1 of publishing'. It explicitly differentiates itself from publishing and names the related tools, so an agent can immediately understand what this step does and what it does not do.

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 explicit when-to-use guidance: it is the first phase of publishing, followed by polling instagram_get_container_status and then calling instagram_publish_media. It also directly distinguishes this tool from the publish step, leaving no ambiguity about the intended 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 only signal openWorldHint and destructiveHint, but the description goes further by explaining the irreversibility, the double-gating mechanism, and the preview behavior when conditions are not met. This adds meaningful behavioral 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?

Three sentences, each carrying essential information: what the tool does, why to prefer an alternative, and when it actually executes. No filler or repetition of schema details.

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 single-comment operation with no output schema, the description fully covers the key facts: irreversibility, safer alternative, required apply flag, environment gate, and preview fallback. An agent has enough context to decide and invoke 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?

The input schema already documents all three parameters at 100% coverage, so the baseline is 3. The description adds value by clarifying that apply is not just a boolean but part of a double-gate with IG_ALLOW_DESTRUCTIVE, which enriches the parameter's semantics without duplicating the 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 precise verb and resource: 'Permanently delete a comment' with the HTTP endpoint DELETE /{comment-id}. It clearly distinguishes itself from reversible moderation by naming instagram_hide_comment as the safer alternative.

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 instructs when to use this tool vs the alternative: 'prefer instagram_hide_comment for moderation you may want to undo.' It also documents the exact conditions required for the action to execute, including apply:true and IG_ALLOW_DESTRUCTIVE=true.

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 and openWorldHint annotations, the description discloses meaningful behavior: the operation is a GET to /{ig-id}, fields the account hides or Meta omits are simply absent rather than errors, and account-controlled free-text fields arrive inside an untrusted content fence. These are valuable runtime expectations an agent cannot 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?

Four tight sentences front-load the main outcome, then add only high-value behavioral caveats. There is no repeated title or boilerplate; every sentence contributes information an agent needs before calling the tool.

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 single-optional-parameter fetch with a provided output schema, the description is complete: it states the resource, the field set, the read-only nature, missing-field behavior, and the security fence. The output schema covers return shape, and annotations cover safety, so nothing essential 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 the single optional account parameter already has a thorough schema description, including the default-profile behavior. The tool description therefore adds no parameter-level meaning, and 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 opens with a specific verb-resource pair — "Fetch the profile of the operated Instagram professional account" — and enumerates exactly which fields are returned (username, display name, biography, website, profile-picture URL, follower/following/media counts). This field list differentiates it from sibling tools such as get_account_insights or get_audience_demographics without needing to read their schemas.

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 makes the tool's scope clear: it fetches the basic profile of the operated professional account, not insights or media. However, it never explicitly tells the agent when to choose this tool over a sibling or when not to use it, leaving usage conditions to be inferred from the field list.

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 mark it read-only; description adds the endpoint and helpful behavior constraints (post-2025 metric set, aggregated-total default, 90-day retention). Some of this duplicates the schema, but endpoint and concise operational context are extra.

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 no fluff: purpose/endpoint first, metric set second, default output and retention third. Every sentence earns its place and the key scope is front-loaded.

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 insight tool with a full input schema, annotations, and an output schema, nothing needed for selection or invocation is missing. The retention bound and metric set are explicitly stated, and output shape is documented elsewhere.

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 all six parameters, enums, defaults, and retention behavior. The description does not add new parameter-level meaning, matching the 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?

Description names the resource ('Account-level insights for the operated Instagram professional account') and gives the GET endpoint, making the operation and scope explicit. 'Account-level' differentiates it from media-level and audience-demographic insight siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Clear context: this is for account-level metrics on an Instagram professional account, with default aggregation and a retention bound. It does not explicitly name alternatives or exclusions, but the account-level framing is enough to route an agent away from media-level and demographic tools.

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 mark this as read-only, and the description adds useful behavioral detail: it names the endpoint, clarifies that demographics use timeframe rather than since/until, and discloses the 100-follower threshold and Meta's error behavior. This is valuable context beyond the structured 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 dense sentences with no filler. The primary definition is front-loaded, followed by the most operationally important constraint and error behavior. Every sentence 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?

The description is complete for a read-only insights tool: it states scope, prerequisites, the endpoint, and a key failure mode. Since an output schema exists, the description need not detail return values, and the input schema documents all parameters thoroughly.

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 already covers all parameters with 100% description coverage, so the baseline is 3. The description adds extra value by emphasizing the timeframe requirement and the 100-follower rule, and by clarifying the distinction between follower and engaged-audience demographics, which enriches the parameter meaning.

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 clearly identifies the resource (audience demographics for the operated account), the operation (breaking down followers/engaged audiences), and the underlying endpoint and metric type. This distinguishes it from siblings like get_account_insights or get_media_insights without needing to inspect schemas.

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 concrete usage context: a timeframe is required and the account must have at least 100 followers, with a note about the resulting error. It does not explicitly name alternatives or say when not to use this tool, but the context is clear enough for selection.

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 annotation, the description discloses important behavior: moderation state context, inline replies, fenced untrusted text, omission rather than nulling of undisclosed fields, and error behavior for deleted comments. This is rich, non-obvious 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 concise sentences, each carrying useful information. The primary purpose is front-loaded, followed by relevant behavioral and edge-case details 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?

For a read-only single-resource fetch, the description covers selection, return context, security treatment of text, null/omission semantics, and error behavior. The output schema fills in the exact return shape, so nothing critical 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 parameters are already well documented. The description adds only marginal value about what the id refers to and does not meaningfully extend the schema's parameter explanations.

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: 'Fetch a single comment by id.' It clearly defines the tool's scope and distinguishes it from siblings like instagram_list_comments, instagram_create_comment, and instagram_delete_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?

The description gives clear context: use this when you need one specific comment by id. It does not explicitly state when not to use it or name alternatives, though the schema's commentId reference to instagram_list_comments provides a helpful source hint.

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 description labels the operation 'Read-only' and reinforces the readOnlyHint annotation while adding behavioral context: status meanings and the correct polling/recreation policy. It does not contradict 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?

The description is compact and front-loaded with the core purpose before the status list and action guidance. Every sentence carries decision-relevant information, 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?

For a status-polling tool with an output schema and readOnlyHint/openWorldHint annotations, the description is complete: it covers the status set and the agent's next actions. The only implied detail, that PUBLISHED means already published, is straightforward enough not to be a 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 description coverage is 100%, so the schema already documents containerId and account. The description focuses on output status values rather than parameter meanings, so it adds no extra parameter semantics; the 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?

The description opens with a specific verb and resource: 'Read a media container's processing state,' and enumerates the exact status values. This clearly separates it from siblings like instagram_get_media by focusing on container processing status rather than media metadata.

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 explicit workflow guidance: publish only when FINISHED, keep polling on IN_PROGRESS without recreating, and recreate on ERROR/EXPIRED. This tells the agent when to use this tool and when to interact with create/publish siblings instead.

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 annotation, the description discloses meaningful behavior: carousel children are included, captions are returned as fenced untrusted text, undisclosed fields are omitted rather than nulled, and deleted/expired objects produce errors. This gives an agent a strong model of what to expect.

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-load the core action and then add the most important caveats: children inclusion, caption trust boundary, field omission behavior, and error conditions. There is no wasted wording.

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 does not need to explain return structure. It covers the critical non-obvious behaviors—omitted vs null fields, error-on-deleted/expired, and caption security—making the tool fully callable by 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 100%, so the schema already documents both parameters well. The description adds little parameter-specific meaning beyond confirming that the operation is by id, which is adequate given the high schema coverage.

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 clearly states the operation: fetching a single media object by id, which distinguishes it from list-style siblings like instagram_list_media. Mentioning carousel children under `children` adds specific resource detail that makes the tool's scope 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?

The description gives clear context: this is for a single media object by id rather than a list or a specific sub-resource. It does not explicitly name alternatives or state when not to use it, but the 'single media object by id' framing makes the intended use reasonably obvious.

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 the description adds meaningful edge-case behavior: metric validity depends on media_product_type, invalid combinations can be rejected client-side, and expired stories or pre-professional media may return empty or error. This goes well beyond the structured 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 sentences carry the essential information with no filler. The endpoint and primary purpose are front-loaded, followed by the most important usage caveats. Every sentence 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?

The tool is moderately complex due to metric-type variability and edge-case failures, and the description covers both. With an output schema present and readOnlyHint true, the description provides enough context for an agent to select and invoke the tool correctly without missing critical behavior.

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. The description adds value by explaining the interaction between media_product_type and metrics, specifically that supplying the product type enables client-side rejection of invalid combinations, which is not fully captured in the individual parameter descriptions.

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 clearly states the tool retrieves insights for a single media object and includes the specific API endpoint. It also highlights that the valid metric set varies by media_product_type, distinguishing this tool from account-level analytics siblings like instagram_get_account_insights.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear operational context: supply media_product_type to get client-side validation of metric/type combinations, and be aware that pre-professional media or expired stories may return empty or error. It does not explicitly name alternative tools, but the 'single media object' scope makes the intended use clear 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 declare readOnlyHint=true and openWorldHint=true, so the description is not required to restate safety. It adds useful behavioral context beyond the annotations: data covers only the last 30 days, and the metric is on a deprecation watch-list and may return a 'metric no longer available' error in future API versions. This is meaningful extra transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded: the core result is stated first, followed by the endpoint, the data window, and a concise deprecation warning. Every sentence adds relevant information without 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-optional-parameter read-only tool with an output schema, the description covers the essential context: what the result represents, the API call, the time window, and a known failure mode. Nothing critical is missing for an agent to invoke it 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?

The only parameter, 'account', is fully documented in the input schema with an explanation of multi-account behavior and the default profile. Since schema description coverage is 100%, the description does not need to compensate, and adding repeated parameter details would be redundant.

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 and metric: 'Hourly distribution of when the account's followers are online' with the exact endpoint path and metric 'online_followers'. This clearly distinguishes it from neighboring insight tools 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 description makes the use case obvious: use this tool when you need the hourly online-followers distribution for the last 30 days. It also provides a deprecation caveat that helps an agent decide whether relying on this metric is appropriate, though it does not explicitly name alternative tools or exclusion 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?

The description adds meaningful behavioral detail beyond the annotations: quota_total is read live from Instagram and never hardcoded, remaining is derived only when total is known, and a carousel counts as one post. This gives the agent accurate expectations about the data source and derived fields without contradicting the readOnlyHint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact yet information-dense, with the core purpose front-loaded and each subsequent sentence explaining a relevant behavioral nuance. No words are wasted, and the read-only note reinforces the existing annotation.

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 the simple input schema, the presence of an output schema, and the read-only annotation, the description covers everything an agent needs: what the fields mean, how the quota total is sourced, and when remaining is available. No critical guidance 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?

The single optional parameter 'account' is fully documented in the schema, including its default behavior. The description does not need to add parameter details, though it also does not clarify how the account parameter relates to the quota result beyond the general phrasing.

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 uses a specific verb ('Report') and resource ('the account's content-publishing usage against its rolling-window quota'), making the tool's function unmistakable. It clearly distinguishes this as a read-only quota check rather than a posting or content-management operation.

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 use case is implied: an agent would call this to check publishing quota before posting. However, the description does not explicitly state when to use it versus alternatives, nor does it mention any related posting tools or conditions for choosing this 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 idempotentHint annotation, the description explains exactly what idempotency means here: hiding an already-hidden comment leaves it hidden. It also discloses that the operation is reversible and that preview mode is the default, with a clear write-mode toggle.

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 carry the endpoint, moderation intent, idempotency, preview mode, and the apply mechanism. The most decision-relevant facts are front-loaded, 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?

Given the tool's low complexity, the provided annotations, and full schema coverage, the description is complete. It covers what the action is, how to perform it, its reversibility, its idempotency, and how to switch from preview to actual execution.

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 adds value by mapping commentId into the endpoint path and clarifying the apply parameter's role in preview vs. actual write, including the IG_WRITE_MODE environment variable fallback.

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 clearly states the tool hides a comment, gives the exact endpoint semantics (POST /{comment-id}?hide=true), and frames it as reversible moderation preferred over deletion. This distinguishes it from sibling tools like instagram_delete_comment and instagram_unhide_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?

Explicitly says hide is preferred over delete for moderation, implying delete is the non-reversible alternative. It also gives precise invocation guidance: preview by default, then re-run with apply:true or set IG_WRITE_MODE=apply to perform the change.

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 mark the operation as readOnlyHint and openWorldHint, and the description adds substantial behavioral detail beyond those: newest-first ordering, cursor pagination, single-page default, fetchAll aggregation up to a server cap, the paging.truncated sentinel, and a security warning that comment text and usernames are untrusted fenced data. This is far richer than the 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?

The description is three dense, purposeful sentences with no filler. The first sentence front-loads the core purpose and key traits (top-level, newest first, threaded replies, pagination), the second explains pagination and aggregation behavior, and the third delivers a concise security warning.

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 the readOnlyHint/openWorldHint annotations and the availability of an output schema, the description covers all essential operational details: default pagination, fetchAll behavior, truncation signaling, and untrusted-text handling. An agent has enough context to invoke the tool correctly and interpret results safely.

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, but the description adds meaningful semantic context beyond the schema: it explains what fetchAll actually does (aggregate to IG_MAX_ITEMS and set truncated), how threaded replies appear inline under 'replies', and the pagination semantics. This strengthens caller understanding without restating the 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?

The description clearly states the verb and resource: it lists top-level comments on a media object, with concrete details about ordering (newest first), pagination, and inline expansion of threaded replies. This distinguishes it from sibling tools like instagram_get_comment, which retrieves a single comment, and from listing 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 description clearly explains how the tool behaves by default (single page) and when to use fetchAll, giving practical usage context. However, it never explicitly names alternatives like instagram_get_comment or states conditions under which this tool should not be used, so there are no explicit 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 only declare readOnlyHint and openWorldHint; the description adds substantial behavior beyond that: cursor pagination semantics, the default single-page return with fetchAll aggregation up to a server cap, paging.truncated flag semantics, captions being fenced/untrusted text, and specific fields (like_count, media_url, story counts) that may be absent. This is rich behavioral disclosure that does not contradict the read-only 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?

Four dense sentences with zero filler. The core purpose is front-loaded, followed by pagination behavior, a security-relevant caption warning, and a field-absence caveat — each sentence 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 an output schema present, return-value structure doesn't need explanation, and the annotations cover safety. The description covers scope, ordering, pagination defaults, aggregation cap behavior, truncation signaling, data trustworthiness, and potential missing fields — nothing an agent needs to call or interpret this tool correctly is omitted.

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 fetchAll and limit descriptions in the schema already state the server-cap and truncation behavior nearly verbatim, so the tool description mostly restates what the schema provides rather than adding new parameter-level meaning.

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: "List the operated account's own media (feed posts, reels, stories, albums), newest first, cursor-paginated." The phrase "own media" explicitly distinguishes this from siblings like instagram_list_tagged_media and instagram_list_comments, and the enumerated media types remove any ambiguity about scope.

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 clear operational context: default single-page behavior versus fetchAll aggregation, the IG_MAX_ITEMS cap, and the paging.truncated signal. The "own media" scoping implies when to use this over tagged-media or comment tools, though it never names an alternative explicitly.

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 readOnlyHint and openWorldHint, so the burden is lower. The description adds useful behavioral context: captions and usernames are fenced, untrusted text, and results are newest-first and cursor-paginated, giving the agent security and ordering expectations 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?

Three tight sentences, front-loaded with the core action and scope. The caveat about @mentions and the untrusted-text warning are purposeful; there is no filler or repetition of schema details.

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 paginated list tool with a full input schema and an output schema, the description is complete. It covers scope, ordering, pagination, the mention distinction, and the security-relevant fenced-text behavior, leaving no obvious gap an agent needs to resolve elsewhere.

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 each parameter is already fully described in the input schema (after, limit, account, fetchAll). The description adds no additional parameter-specific semantics beyond cursor-paginated context and the fenced-text caveat, which maps to the response rather than parameters.

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 and resource ('List media the operated account has been TAGGED IN') and anchors it to the /tags edge. It actively distinguishes tagged media from @mentions, which prevents confusion with siblings or other IG endpoints.

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 states the capability precisely and includes an explicit when-not: tags are not @mentions, and pull-based @mention discovery is a separate Path-B-only capability. It also signals ordering (newest first) and pagination so an agent knows what to expect when choosing this 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?

The description goes well beyond annotations by disclosing that preview is the default and performs nothing, that apply:true is required to write, that a poll-timeout returns status=in_progress with resume_container_id, and that re-running must resume rather than create a duplicate. It also clarifies that Instagram validates image format and dimensions at fetch time, which is essential behavioral 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?

The description is compact and front-loaded: the first sentence states the primary action and workflow, and each following sentence earns its place by covering preview behavior, resume edge cases, and validation expectations. There is no repetition of schema content or 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 7-parameter, open-world tool with no output schema, the description covers the key operational flow, the preview/write distinction, the resume path, and the duplicate risk. The main gap is that it does not describe what a successful publish or a preview response returns, which would help an agent handle results without an 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%, and the schema already documents apply, imageUrls, resumeContainerId, and the duplicate-avoidance behavior. The description repeats and reinforces the workflow but does not add new per-parameter semantics beyond what the schema provides, so the 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?

The description starts with a specific, scoped action: 'Publish a single feed image, or a 2–10 image carousel, in one call'. It clearly differentiates this from reel/story posting and from the lower-level container/publish siblings, so an agent knows exactly what resource this tool acts on.

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 clear context for when to use this tool: for a single feed image or carousel, in one call, versus the alternative of manually creating containers and publishing. It does not explicitly name sibling tools or state when not to use them, so it stops short of a fully explicit routing guide.

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 description adds substantial behavior beyond the annotations: reels can take a while to process, preview is non-mutating, polling can time out into a resumable in_progress state, and video constraints are only enforced by Instagram at fetch time. It also warns against duplicate posts when resuming. This is exactly the kind of behavioral nuance annotations alone 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?

The description is compact and front-loaded with the main operation, then covers preview semantics, resume flow, and validation caveats in just three sentences. Every sentence carries critical information with no filler or redundancy.

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 complex 9-parameter write tool with no output schema, the description covers the key edge cases: preview behavior, polling budget, resume semantics, and deferred validation. It does not describe what a successful final response looks like (e.g., published media ID or URL), which is a minor gap given no output schema is present, but the guidance is otherwise strong enough for an agent to use the 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%, so the schema already documents all nine parameters well. The description adds a little extra value by clarifying resumeContainerId's role in finishing an in_progress post and by noting videoUrl is validated only on Instagram fetch, but it largely reinforces 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?

The description states a specific verb and resource: 'Publish a reel in one call' and names the actual operation sequence (create REELS container, wait for processing, publish). It differentiates this tool from sibling tools by emphasizing the one-call reel flow vs lower-level container creation/publishing, and from image/story posts by resource 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?

The description gives clear context on when to actually write vs preview ('Preview performs nothing'), when to resume vs create new ('re-run with apply:true and resumeContainerId to finish... never create a new post'), and warns that validation happens on Instagram's side. It does not explicitly name sibling alternatives like instagram_create_media_container, but the one-call versus multi-step distinction is strongly 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?

The description discloses key behaviors beyond the annotations: the tool creates a STORIES container, waits for processing, and then publishes; preview is non-mutating; a timed-out processing returns status=in_progress with a resume_container_id; and stories expire after 24 hours. This gives the agent a clear model of side effects and failure handling, complementing the sparse annotation hints.

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 cover the core action, input constraints, preview behavior, resume flow, and expiration without redundant wording. The most important operational rules are front-loaded, and every sentence 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 tool with no output schema and moderate complexity, the description covers the full lifecycle: input selection, preview no-op, poll-budget failure and recovery, idempotency guidance, and the 24-hour expiration. An agent has enough information to call and retry this 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?

Although the schema already covers all parameters, the description adds critical semantics: mutual exclusivity of imageUrl and videoUrl, the meaning of resumeContainerId for avoiding duplicate posts, and the fact that preview performs nothing. This goes well beyond the baseline schema descriptions and directly informs correct invocation.

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 opening phrase 'Publish a photo or video story in one call' states a specific verb, resource, and delivery mode, clearly distinguishing it from the multi-step container/publish pipeline and from siblings like instagram_post_reel. It also explains the internal sequence (create container, wait, publish), making the tool's purpose unmistakable.

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 explicit operational guidance: provide exactly one of imageUrl or videoUrl, preview performs nothing, and resume with apply:true plus resumeContainerId when status is in_progress. It does not explicitly name an alternative tool for other use cases, but the instructions for correct usage are concrete and unambiguous.

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 description adds meaningful behavior beyond annotations: publishing is never auto-retried, a repeated publish costs quota and posts a duplicate, and retry requires external confirmation. This complements idempotentHint=false with concrete operational consequences.

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, each earning its place: purpose and outcome, required precondition, and retry/idempotency warning. The critical information is front-loaded and there is 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?

Despite lacking an output schema, the description states the return value (new media id), covers the prerequisite, and addresses the main operational risk (duplicate posts/quota). For a 3-parameter tool with fully documented schema, this is complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already covers all three parameters at 100% coverage, so the description does not need to document them. It does usefully reinforce that creationId must reference a FINISHED container, but adds no substantial parameter meaning beyond the 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 ('publish') and resource ('media container') and identifies this as 'Phase 2 of publishing,' clearly distinguishing it from container creation and status checking. It also describes the outcome: returning the new media id.

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: the container must be FINISHED, and points to instagram_get_container_status to verify. It also gives clear when-not-to-retry guidance: never auto-retry; only retry after confirming the previous call did not already publish.

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 only openWorldHint=true in annotations, the description carries the burden of disclosing side effects. It does this well by stating that the tool previews by default and only performs the write when apply:true is set. The environment-variable override adds useful non-obvious 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?

The description is a single compact sentence that leads with the core purpose, then states the preview behavior and how to perform the write. No filler or redundant detail.

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-parameter tool with a fully-described schema, the description plus schema covers the essential invocation details: endpoint, required parameters, apply semantics, and account defaulting. The main minor gap is not describing what the preview output looks like, but this is not critical 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?

The schema already provides 100% coverage of parameter meanings, so the baseline is 3. The description adds value by explaining that the comment ID maps into the endpoint path and by introducing the IG_WRITE_MODE environment variable as an alternative to the apply 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?

The description opens with a specific verb and resource: 'Post a threaded reply under an existing comment', which clearly distinguishes this from sibling tools like instagram_create_comment. Including the endpoint POST /{comment-id}/replies reinforces the exact operation.

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 clear operational guidance: preview by default, then re-run with apply:true to actually perform the reply. It also mentions the IG_WRITE_MODE=apply environment variable. It does not explicitly name alternative sibling tools, but the 'existing comment' condition makes the use case 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?

Description discloses key behavioral traits beyond annotations: the operation is idempotent (setting an already-held value is a no-op), it runs in preview mode by default, and a real write requires apply:true or IG_WRITE_MODE=apply. The endpoint and its query parameter make the underlying side effect transparent. There is no contradiction with 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 tightly crafted sentences with zero filler. The core capability and endpoint appear first, followed by the idempotent behavior and the preview/apply pattern. Every clause adds useful guidance.

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-parameter mutation toold with no output schema, the description covers the essential invocation framing: endpoint, state change, idempotency, and preview/apply mode. It does not describe return values or effects on existing comments, but these are not required to select or invoke the tool correctly. The description is complete enough for an agent to know what to do.

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 covers the parameters at 100%, so baseline is 3. The description adds meaningful operational context: it clarifies the apply flag's preview/write duality and introduces IG_WRITE_MODE as an alternative way to set apply mode. It also reinforces that enabled directly maps to comment_enabled in the endpoint. This goes beyond schema text without repeating it.

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 action verb ('Toggle') on a specific resource ('a media object') and names the precise effect ('accepts new comments'). Includes the API endpoint, which further disambiguates it from sibling tools that manage individual comments. An agent can clearly distinguish this from instagram_hide_comment or instagram_delete_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?

The description makes the use case unmistakable: togggling the comment-enabled state of a media object. It does not explicitly name alternatives or when-not-to-use conditions, but the preview-by-default and apply pattern gives clear operational context for how to invoke. The uniqueness of the capability relative to sibling comment-management tools is sufficiently 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?

Beyond the readOnlyHint annotation, the description discloses path-dependent behavior: Path B uses debug_token to report validity, scopes, expiry, and days-left with a refresh warning, while Path A has no introspection endpoint and reports expiry honestly as unknown. This is substantial behavioral context that annotations alone do not 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?

The description is front-loaded with the core purpose, then efficiently organizes path-specific details in separate clauses, ending with the read-only note. Every sentence and clause adds necessary information without fluff or redundancy.

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 the output schema is present and the annotation declares read-only, the description fully covers the operational behavior: it states what is reported, how each auth path is handled, the warning behavior, and the honest unknown for Path A. Nothing essential for an agent to select and invoke the tool 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?

The single optional parameter 'account' is already fully described in the schema with a clear explanation and default behavior. With schema coverage at 100%, the description doesn't need to add parameter detail; it doesn't, so the baseline score of 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?

The description leads with a specific verb-resource pair ('Report the active credential') and enumerates exactly what is reported: auth path, token configured, account ID, validity/scopes/expiry on Path B. It clearly distinguishes itself from sibling media/account operations by focusing solely on token/credential status.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool: when credential status, expiry, or account resolution are needed. It doesn't explicitly name alternatives because no sibling tool serves this purpose, but the coverage of what it does makes the use case unambiguous and there are 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?

Beyond the openWorldHint and idempotentHint annotations, the description discloses the preview-by-default mode, the need to re-run with apply:true to perform the write, and the IG_WRITE_MODE=apply environment override. This gives the agent essential behavioral information beyond the structured 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?

The description is three sentences with no filler. It front-loads the core operation, then idempotency, then the execution workflow. Every sentence adds necessary 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?

For a simple three-parameter idempotent operation, the description covers the operation, side-effect control through preview mode, and the exact execution path. No output schema exists, but the preview/apply mechanism is sufficiently described for an agent to invoke the 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 coverage is 100%, so the baseline is 3. The description adds value by explaining the default preview behavior and introducing IG_WRITE_MODE=apply as an alternative to the apply parameter, which is not present in the 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?

The description uses a specific verb and resource: 'Unhide a previously hidden comment' with the API endpoint POST /{comment-id}?hide=false. It clearly distinguishes this from sibling tools like instagram_hide_comment by stating the inverse operation directly.

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 clear context: use this tool to unhide a previously hidden comment, and it explains the idempotent behavior when the comment is already visible. It provides a preview/apply workflow, though it does not explicitly name sibling alternatives or state when not to use it.

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