Glim

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds genuinely new operational context: irreversibility and a required user-confirmation step before invocation. It stops short of stating permission/ownership failure modes or what happens when the ID belongs to another account's post, which keeps it from 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?

One sentence, front-loaded with the destructive action and its scope, followed by the risk warning and the alternative. Every clause earns its place with no 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 one-parameter destructive tool with no output schema and rich annotations, the description covers destruction, confirmation protocol, and the sibling alternative. Only the source/format of comment_id and failure behavior are left unaddressed.

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

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

Schema coverage is 0% and the single parameter is documented only by a regex pattern with no description. The phrase 'comment on the account's own post' implicitly constrains which comment_id is valid, but the description never explains the identifier format or where to obtain it, so it only partially compensates.

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 ('Permanently delete a comment') and narrows scope with 'on the account's own post', which also distinguishes it from other comment operations. The sibling named in the description (ig_hide_comment) makes the boundary explicit.

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

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

Explicitly says to confirm with the user first and to consider ig_hide_comment instead, i.e. it names both the precondition and the softer alternative. An agent has a clear decision rule without opening any schema.

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, idempotent and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: data can lag up to 48 hours, and 'views' replaced the retired 'impressions' metric — essential for interpreting and trusting the numbers. It stops short of describing aggregation/rounding behavior or empty-window responses.

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: scope and metric list first, then the two caveats an agent actually needs (lag, renamed metric), then the routing hint. No filler and no repetition of the schema's parameter docs.

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

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

No output schema exists, but the description enumerates the metric set and the response_format parameter covers the return shape, so an agent knows what it gets back. A brief note on the default metric subset or empty-data behavior would close the last gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns extra by clarifying metric nomenclature ('views' replaced 'impressions') and restating the 1-30 day window, which maps directly to the 'days' parameter and prevents an agent from requesting a retired metric name. It adds meaning rather than repeating 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+resource ('account-level totals over the last N days') and enumerates exactly which metrics come back (views, reach, accounts engaged, interactions, likes, comments, shares, saves, follows, link taps). It also names the nearest sibling, ig_get_audience, so an agent can tell the two apart 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 explicit routing: 'For audience age/gender/location use ig_get_audience,' which is a concrete alternative with its selecting condition. It also states the window constraint (1-30 days). It doesn't address when to prefer ig_get_media_insights or account vs. per-post scope, so the guidance is clear but not exhaustive.

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/idempotent/non-destructive, so they carry the safety profile; the description adds real behavioral context the annotations cannot — the 100-follower threshold and the live-account requirement, both of which determine whether the call succeeds. It stops short of documenting rate limits or what happens below the threshold (empty result vs error).

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

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

Two sentences, no filler, and the resource definition is front-loaded ahead of the eligibility constraint and enum guidance. Every clause carries information an agent would otherwise have to guess.

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

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

No output schema exists, so the description should ideally say something about the returned shape, and it does not — that is the main gap. Against that, it covers the resource, the eligibility precondition, and the primary enum semantics, which is close to what an agent needs given four short enum 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 coverage is only 25% (just response_format), so the description is doing meaningful work by defining the semantics of both 'followers' and 'engaged' and the available breakdown dimensions. But 'timeframe' is referenced only vaguely ('in the timeframe') and the accepted values/behavior of narrowing or widening the window are never explained.

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 first sentence names a specific resource (audience demographics of the account) and enumerates the breakdown dimensions, so an agent can tell this apart from ig_get_account_insights or ig_get_media_insights. It lacks an explicit verb ('Get'/'Retrieve'), but the resource and scope are 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 states a concrete precondition ('Needs at least 100 followers on a live account') and disambiguates the 'followers' vs 'engaged' choice, which is genuine usage guidance. However, it never says when to prefer this over sibling analytics tools like ig_get_account_insights, nor any when-not conditions.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description still adds real value absent an output schema by enumerating the returned fields, including the non-obvious 'carousel slides' payload. It says nothing about auth or rate limits, which is the only remaining gap.

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, and the identity/scope statement plus the return-field list are front-loaded before the ID-provenance note. Every clause carries information an agent can act on.

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

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

For a two-parameter, read-only lookup with complete annotations, the description covers what it returns, how to obtain the ID, and the output-format choice is fully documented in the schema. Nothing an agent needs in order 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% (media_id with a format example, response_format with an enum), so baseline is 3. The description exceeds baseline by documenting value provenance — where valid media IDs are obtained (ig_list_media) — which the schema does not state and which materially reduces bad-ID calls.

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 scope ('one post, reel or carousel by ID') and enumerates exactly what comes back: caption, type, media URL, permalink, likes, comment count and carousel slides. The singular 'one ... by ID' cleanly separates it from the sibling list tool ig_list_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?

Explicitly tells the agent where the required ID comes from ('IDs come from ig_list_media'), which is the main usage prerequisite. It does not spell out exclusions or point at the closest alternative for aggregate stats (ig_get_media_insights), so it stops short of a full when/when-not statement.

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/idempotent/non-destructive, so the safety profile is covered; the description adds genuinely new behavior — metric availability varies by media type, and defaults are chosen automatically unless overridden. It does not say what happens if an unsupported metric is requested (error vs. silently dropped), which is the main remaining gap.

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, no filler, with the highest-value information (what it returns, which media types, auto-selection) front-loaded. 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?

With no output schema, the description usefully enumerates the returned metrics and notes the reel-specific watch time, so an agent knows what comes back. Combined with the ID provenance hint, only minor edge-case behavior (invalid metric handling, response_format mention) is left uncovered.

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?

media_id has no schema description, and the description compensates by specifying its source ('IDs come from ig_list_media') — that is exactly the missing link. It also restates the metrics override with an example matching the schema. response_format is covered by the schema and adds nothing here, which is acceptable.

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 the resource precisely: engagement metrics for 'one post, reel or story', which cleanly separates it from the account-level ig_get_account_insights sibling. The enumeration of metrics (views, reach, likes, comments, shares, saves, interactions) plus the reel-specific 'average watch time' makes the output content concrete. Not a 5 because there's no explicit verb and the per-media vs. account-level distinction is implied by 'one post' rather than stated.

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

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

Gives operational guidance for both decisions an agent faces: the tool auto-selects metrics by post type, and 'pass metrics to choose your own' defines the override path. 'IDs come from ig_list_media' points to the prerequisite call. It stops short of an explicit exclusion (e.g. 'for account-wide totals use ig_get_account_insights').

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/idempotent/non-destructive/openWorld, so the description's job is to add context — it does so with result ordering ('newest first') and the hard cap tied to Instagram's own limit. It omits any note on pagination or rate limits, but with no pagination parameters in the schema that gap is small.

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

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

Two short sentences: scope and ordering first, prerequisite second. Nothing repeats the annotations or the schema verbatim.

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 read-only lookup with no output schema and one required parameter, this covers what an agent needs to invoke it. It could say more about what a returned message contains (sender, timestamp, media), but the response_format option is already documented in the 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 only 33% and only response_format is documented there, yet the description supplies real meaning for limit (why 20 is the ceiling) and for conversation_id (its source tool). The pattern constraint on conversation_id remains unexplained, keeping it short of a 5.

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 ('Read ... messages in one DM conversation') plus scope ('latest', 'up to 20') and ordering ('newest first'), which cleanly separates it from ig_list_conversations and ig_send_message.

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 tells the agent where the required conversation_id comes from ('Get conversation IDs from ig_list_conversations'), a real prerequisite. It stops short of stating when not to use it (e.g., use ig_list_conversations to browse threads first, or ig_send_message to respond).

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuinely non-structured context: that the response discloses demo mode (fictional sample account) vs live, which affects how the agent should interpret every subsequent call. It doesn't cover failure modes for an unconnected account.

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

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

Two short sentences, zero filler, with the resource and returned fields front-loaded and the operational instruction ('call this first') placed last where it reads as a directive. 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 compensates by listing the exact fields returned, and it also explains the demo/live distinction an agent needs to interpret results. Nothing required 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?

There is one optional parameter, response_format, documented at 100% schema coverage with its enum and default. The description says nothing about output format selection, so the schema is doing all the work; 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 (connected Instagram professional account) and enumerates exactly what comes back: username, name, bio, website, followers, following, post count. No sibling tool in the list retrieves profile data, so the resource alone disambiguates it.

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

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

'Call this first to check the connection' gives explicit ordering guidance an agent can act on, which is unusually concrete for a read tool. It does not name any alternative or when-not condition, but for a single-purpose profile fetch there is no plausible competing 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?

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real semantics beyond them: the window is a rolling 24 hours, the limit is usually 100, and carousels count as a single post. The one gap is that it doesn't say what happens when quota is exhausted.

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

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

A single sentence that front-loads the returned value and packs the counting rule into a parenthetical. Nothing is wasted and nothing essential is buried.

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 the return, and it does so qualitatively (count plus limit). For a zero-parameter read tool with full annotation coverage, this is nearly complete; only the exhaustion/error behavior is unstated.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The schema is closed with additionalProperties=false and no fields, matching the description's account-level scope.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource (publishing quota) and metric (posts published via API in the last 24 hours) with the ceiling value. An agent can tell this apart from the posting siblings like ig_publish_post, though it never names an alternative to reinforce that.

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

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

Usage is only implied — the natural reading is 'call this before publishing to check remaining quota', but the description never says when to use it, when not to, or which sibling to pick instead. No prerequisites or rate-limit context for the call itself.

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

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

Annotations already declare non-destructive, idempotent, non-read-only behavior; the description adds the two facts annotations cannot express — the change is reversible and visibility is scoped to the author only. That is meaningful added context, though it says nothing about permission requirements or whether hiding affects comment counts.

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

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

A single sentence that front-loads the action, then the effect, then the alternative preference. 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 two-parameter toggle with no output schema and annotations already carrying the safety profile, the description supplies what matters: reversibility, visibility semantics, and the delete-vs-hide choice. Only minor gaps (permissions, effect on comment counts) remain.

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 50%: the `hide` boolean is documented in the schema itself, and the description reinforces the dual mode ('or unhide it'). The required `comment_id` has a regex pattern but no prose explaining ID format or provenance, so coverage remains partial.

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 (hide/unhide) and resource (comment), plus the precise observable effect: 'only its author still sees it.' That effect definition separates it cleanly from ig_delete_comment, which is the nearest ambiguous sibling.

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

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

Gives a concrete trigger ('e.g. spam or abuse') and routes explicitly away from the destructive alternative with 'prefer this over deleting.' It stops short of stating when unhide specifically is appropriate, but the boolean parameter covers that adequately.

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/non-destructive/openWorld, so the description only needs to add operational detail — and it does: ordering ('newest first') and the returned sub-fields including hidden state. Pagination via cursor is left to the schema rather than described.

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: the first defines the operation and what's returned, the second gives the ID-flow prerequisites. No filler, and the core purpose 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?

With rich annotations, no output schema, and only four params, the description covers what the tool does, what the result contains, and how to get/use IDs. The main residual gap is pagination and page-size guidance.

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

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

Schema coverage is 50%: 'after' and 'response_format' are documented in the schema, while media_id and limit are not. The description compensates for media_id by pointing at ig_list_media as the source, but says nothing about the limit cap or page-size behavior, so compensation is only partial.

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 comments on one of the account's posts') plus scope details: newest-first ordering and included fields (replies, likes, hidden state). This clearly distinguishes it from mutation siblings like ig_reply_to_comment or ig_hide_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 names the downstream consumers of the returned comment IDs (ig_reply_to_comment, ig_hide_comment, ig_delete_comment) and the upstream source of media_id (ig_list_media). That's solid routing, though it doesn't state when to prefer this over e.g. ig_get_media for inspecting a post.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is handled; the description adds value with the required scope (instagram_business_manage_messages) plus sort order and what identifiers come back. Remaining gap is pagination behavior, which is left entirely to 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?

Two sentences, both earning their place: the first covers ordering and content, the second covers return values, intended downstream tools, and auth scope. Ordering information 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?

No output schema exists, so the description correctly takes on the job of describing return contents (conversation IDs, IGSID). Pagination via the 'after' cursor and the response_format choice are only in the schema, a modest gap for a small read tool.

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

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

With 67% schema coverage across 3 params, the schema documents 'after' and 'response_format'; only 'limit' lacks a description. The description adds no parameter detail at all (no mention of cursor paging or page size), so it neither compensates nor regresses relative to 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?

States a specific verb and resource ('List the account's Instagram DM conversations'), specifies ordering ('most recent first') and payload ('with who they're with'), and even names the downstream consumers (ig_get_messages, ig_send_message). An agent can distinguish it from ig_list_media or ig_list_comments 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?

Makes the use case explicit by framing this as the discovery step that produces conversation IDs for ig_get_messages and IGSIDs for ig_send_message. It does not state exclusions or note that it cannot filter, but the entry-point role is 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?

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds genuinely useful behavior beyond that: result ordering (newest first), that results are paged, and that an 'after' cursor is returned when more exist. It says nothing about rate limits, page-size defaults, or empty-account behavior, so it stops short of rich disclosure.

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

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

Three tight sentences with zero filler, and the core capability plus return shape is front-loaded before the sibling routing. Slightly more text than the minimum, but every sentence carries distinct 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?

There is no output schema, and the description does a fair job compensating by naming the return shape and cursor. However, an agent still cannot tell whether the response envelope includes media type, timestamps, or media IDs needed to feed ig_get_media, which is the natural next call.

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 all three parameters are already documented, which sets the baseline at 3. The description does add meaningful usage semantics for 'after' by explaining the round-trip (result gives a cursor, pass it back), but says nothing about 'limit' bounds or 'response_format' behavior.

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 account's posts, reels and carousels') plus the returned fields (likes, comment counts) and ordering (newest first). It explicitly distinguishes itself from ig_get_media and ig_get_media_insights, so an agent can route 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?

Names both alternatives and the condition that selects them: ig_get_media for a single post's full details, ig_get_media_insights for views/reach. The pagination instruction ('pass back the after cursor') further tells the agent how to continue, leaving nothing to inference.

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

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

Annotations only declare non-read-only, non-destructive, non-idempotent, open-world; the description adds the critical facts that nothing is public yet, that a human confirmation step is expected before publishing, and that drafts expire after 24 hours. It also discloses hard media constraints (public https URL, JPEG for photos, MP4/MOV 3s-15min for reels), which are behavioral preconditions not captured by annotations.

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

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

Front-loaded with the step and return value, then constraints, then type semantics, then an example. No sentence is filler and the ordering follows how an agent would actually need the 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 an 8-parameter mutation with no output schema, the description covers the staging lifecycle, the human-in-the-loop handoff, expiry, media validation rules, and per-type expectations. Remaining parameter detail is already carried by the schema's own descriptions.

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 88%, so most parameters are already documented, but the description adds real value by explaining each enum value of `type` ('image' one photo, 'carousel' 2-10 photos/videos, 'reel' one video, 'story' one photo or video with no caption) — the schema's enum has no per-value descriptions. The worked example maps a natural-language request onto type/media_url/caption, though alt_text, cover_url, share_to_feed and media_kind are left entirely to 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 and resource ('upload media to Instagram as an unpublished draft') plus the concrete return value ('preview with a container_id'). The title's 'step 1 of 2' and the explicit handoff to ig_publish_post make it unmistakable versus its sibling.

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: use this to stage, show the preview and get a clear yes, then call ig_publish_post with the container_id. It also names the alternative tool and the condition that selects it, and warns about the 24-hour draft expiry.

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 meaningfully beyond annotations: the action is irreversible through the API and requires prior user confirmation. It also states the return payload (new post's ID and link), which matters since there is no output schema. The one gap is that it doesn't say whether the preview expires or what error state a stale container_id produces, so the irreversibility warning isn't fully operationalized.

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

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

Three short sentences, front-loaded with the step and the action, with the irreversibility warning and confirmation gate immediately after. Every sentence contributes, but the description leans entirely on the sentence-per-idea structure without any extra framing, so it earns a solid but not standout mark for economy.

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 one-parameter, no-output-schema publish tool, the description covers the workflow position, the confirmation prerequisite, the irreversibility, and the return values. Nothing an agent needs in order 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 coverage is 100% and the single parameter is already documented as coming from ig_prepare_post. The description only echoes the provenance constraint already in the schema, adding nothing about format or lifetime of the container_id. Baseline 3 applies when the schema does the heavy lifting.

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: making a draft from ig_prepare_post public on the account. It explicitly frames itself as step 2 of the ig_prepare_post workflow, so an agent can distinguish it from the prepare sibling without opening either schema.

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

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

Gives an explicit prerequisite: only call after the user has seen the ig_prepare_post preview and confirmed. That is a clear when-to-use gate plus the alternative step named, leaving nothing to inference for a high-stakes publish action.

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

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

Annotations already declare the write/non-idempotent/open-world profile, so the description's job is to add context — and it does: replies are public, they appear under the account's identity, and nested replies are rejected. It doesn't mention error behavior or rate limits, but for a mutation tool with full annotation coverage this is a solid addition.

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

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

Three short sentences, zero filler, and the operating instruction (which id to pass) is front-loaded immediately after the one-line purpose. Every sentence carries a distinct constraint.

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?

Covers purpose, mode selection, visibility and the top-level-only restriction for a 3-parameter mutation tool with no output schema. Slightly short of complete because it doesn't say what a successful response looks like or how conflicting media_id + comment_id is handled at runtime.

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

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

Schema coverage is only 33% (media_id and comment_id are undocumented), and the description compensates by assigning each one a concrete mode and implying mutual exclusivity with "or". The required `message` parameter is left to the schema, which is acceptable given its own description and length bounds.

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 a reply / add a top-level comment) and resource, and the two-mode structure (comment_id vs media_id) makes it distinct from siblings like ig_delete_comment, ig_hide_comment and ig_list_comments. An agent can tell exactly what this tool produces 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?

Explicitly routes the caller: use comment_id to reply under a comment, media_id for a new top-level comment, plus a platform constraint (replies only to top-level comments) that pre-empts a failed call. No sibling tool is named as an alternative, which keeps it just below 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?

Goes well beyond the readOnly/idempotent/destructive annotations by disclosing Meta's hard limit of 30 unique hashtags per 7 days per account and the requirement for a Facebook Login token with Instagram Public Content Access. These are exactly the constraints an agent needs before invoking and are not expressible in 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: purpose and modes first, then operational constraints, then a concrete example. No filler, and the most decision-relevant information (the two modes) 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?

Covers purpose, modes, auth prerequisites, rate limits and an example, which is substantial for a 4-parameter read tool with no output schema. It does not clarify what a result looks like (e.g. media items, pagination) or the meaning of 'limit', leaving a small gap.

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

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

Schema coverage is 50%: 'hashtag' and 'response_format' are documented in the schema while 'kind' and 'limit' are not. The description fills the most important gap by defining 'kind' as 'top' vs 'recent (last 24 hours only)'; 'limit' remains only inferable from its 1-50 bounds.

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 ('Find public posts for a hashtag') and immediately qualifies the two modes ('top' most popular vs 'recent' last 24 hours). It is unambiguous what the tool does, though it makes no reference to any sibling tool since none of them overlap in function.

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 example ('What's trending under #punefood?') anchors a concrete use case, and the top/recent distinction tells the agent which mode fits which intent. There are no explicit exclusions or named alternatives, but the surrounding siblings are messaging/media tools that don't compete, so context is clear.

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

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

Annotations already indicate this is a non-idempotent, open-world mutation. The description adds important policy context beyond annotations: the 24-hour messaging window, the 1000-byte limit, sending 'as the account,' and the instruction to confirm text with the user first.

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 four short, front-loaded sentences. Each sentence adds useful information: the operation, the 24-hour constraint, the recipient_id source, the size limit, and the confirmation step.

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 only two parameters, no output schema, and annotations that already declare mutation behavior, the description covers the critical operational details an agent needs: who can be messaged, how to obtain the recipient ID, the message size limit, and the need for user confirmation.

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

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

Schema description coverage is 0%, so the description must compensate. It explains that recipient_id is an Instagram-scoped ID available from ig_list_conversations or ig_get_messages, and it reiterates the 1000-byte limit for text, adding practical meaning beyond the raw 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 opens with a specific verb and resource: 'Send a text DM as the account.' This clearly distinguishes it from sibling tools like ig_reply_to_comment or ig_get_messages.

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

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

It gives a critical usage condition (only within 24 hours of the person's last message) and a confirmation requirement. It also points to ig_list_conversations and ig_get_messages for obtaining recipient_id, though it does not explicitly compare against all alternatives.

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