Instagram

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

The description adds useful behavior beyond the annotations: config header yields a permanent connection, while passing a token yields a session-only login, and no args returns a link. It does not fully spell out side effects or success/failure return values, but annotations already cover idempotency and non-destructiveness.

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 dense and front-loaded, with no fluff, but the long single sentence with parenthetical clauses and multiple alternatives could be structured into clearer separate instructions. Still, every part 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 one-parameter auth tool with no output schema, it covers the no-arg return (the link), the token-paste path, and the persistent-config alternative. It doesn't state the response on a token success/failure, but the invocation guidance is sufficient for an agent to call 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?

With 0% schema coverage, the description carries the full burden for the optional `token` parameter. It explains that token is a JWT/access token pasted by the user and how to pass it, compensating well for the bare 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 identifies the tool as MCP.AI authentication for IDE agents, with a concrete browser-login + access-token flow and two invocation paths (no args for a link, token for login). This specific verb+resource is unambiguous and easily distinguished from the unrelated calculo_* sibling tools.

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

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

It explicitly differentiates the persistent config-header approach ('best... permanent, non-expiring') from the session-only paste/login path, and states exactly when to call with no args versus with { token }. This gives the agent clear selection criteria for both setup and invocation.

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 this is read-only, idempotent, and non-destructive. The description adds useful behavioral detail beyond that by specifying the two main response states: authenticated:true with empty pending[] when all providers are connected, and connect_url plus per-install URLs when credentials are missing. This helps an agent predict 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?

The description is compact, front-loads the core purpose, and then adds only the essential conditional details. Every sentence contributes meaningful information, and there is no waste.

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

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

For a zero-parameter read-only status tool with no output schema, the description is complete enough. It tells the agent what information will be returned, what the success condition looks like, and what happens when credentials are missing. The low complexity means no additional guidance is required.

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 has zero parameters, so the description does not need to explain any input semantics. The baseline of 4 applies because there is no parameter burden at all.

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's purpose: returning connection status and URLs. It distinguishes connect from its sibling authenticate by framing it as a status/read operation rather than an action, and the conditional output descriptions reinforce this.

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 clear that this is the tool to call when checking connection state or getting URLs. It does not explicitly mention alternatives like authenticate, but the context strongly implies connect is for status checking rather than initiating authentication, so usage is clear without being fully explicit.

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

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

The description discloses that the operation returns a job_id, indicating an asynchronous process, and that it can handle multiple targets. However, it does not explain polling via a job status tool, potential rate limits, or side effects beyond the follow action. Annotations only state readOnlyHint=false and destructiveHint=false, so the job_id return adds some value but leaves deeper behavior undisclosed.

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, well-structured sentence that front-loads the primary action and input format, then notes the return value. Every word contributes meaning with no redundancy 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?

Given the lack of an output schema and sparse annotations, the description is incomplete. It omits the role of the 'account' parameter, does not mention that the returned job_id should be used with instagram_actions_get_job_status, and provides no context about async processing or prerequisites. The agent has enough to start but not enough to reliably invoke the tool in all scenarios.

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 clarifies that 'targets' are usernames, but it says nothing about the optional 'account' parameter, leaving its purpose ambiguous. The agent cannot confidently decide whether to include 'account' and what value to use.

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 action ('Follow'), the resource ('Instagram users'), and the required input format ('by @username'). It also indicates support for multiple targets ('one or more'), which aligns with the array schema. This clearly distinguishes it from sibling tools like instagram_actions_unfollow or like actions.

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 intended use is implied by the verb and resource, but there is no explicit guidance on when to choose this tool over alternatives or any prerequisites (e.g., authentication, chosen account). No exclusions or conditional context are provided, leaving the agent to infer usage from the tool name.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds the context that it targets previously started actions and supports bulk job_ids, but it does not disclose response format, error behavior, or account handling.

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 tight sentences with no filler. The core purpose is front-loaded, and the bulk support note adds useful information without bloating the text.

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 status tool, the description is mostly adequate, but it lacks guidance on how account interacts with job lookups and provides no detail about the returned status/progress/result shape. The lack of an output schema makes this slightly more important.

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 0% schema description coverage, the description partially compensates by explaining job_id as the identifier of a previously started action and job_ids as bulk input. However, the optional account parameter is never explained, leaving a meaning gap.

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

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

The description clearly states the action: 'Get the status/progress/result of a previously started action by its job_id.' This is a specific verb plus resource and distinguishes the tool from siblings like listing jobs or sending 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?

The description implies it should be used after an action has been started and mentions bulk execution through job_ids, but it does not explicitly compare against alternatives such as instagram_actions_list_jobs 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.

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

Annotations mark this as a non-read-only, mutating action. The description adds the key behavioral fact that it is asynchronous: it returns a job_id and requires polling instagram_actions_get_job_status. It also warns about input requirements, though it does not detail side effects or failure modes.

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 a high density of useful information: the action and input format come first, followed by the async workflow. There is no filler or repetition of structured data.

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 covers the primary parameter and the return workflow, which is enough for a first call. Still, the optional account parameter is undocumented, and because there is no output schema, the return value is only minimally described as a job_id.

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

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

With 0% schema description coverage, the description meaningfully clarifies the `posts` parameter as accepting post URLs or shortcodes and excluding numeric media IDs. However, the optional `account` parameter is left completely unexplained, so the description only partially compensates for the bare 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 states a specific verb ('Like') and resource ('one or more Instagram posts'), and further distinguishes the addressing mode from the official numeric media ID API. This naturally separates it from siblings like instagram_actions_like_comment without confusion.

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 clear context on how to call the tool: use post URLs or shortcodes, not numeric media IDs, and poll the named job status tool afterward. It does not explicitly enumerate when to use this tool versus alternatives, so it stops short of full exclusionary guidance.

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

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

Annotations only indicate readOnly=false and destructive=false, so the description carries the behavioral burden. It usefully discloses that this is an asynchronous operation returning a job_id and that polling via instagram_actions_get_job_status is required, plus that wrong-namespace IDs are rejected.

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 no filler. The most critical operational constraint (ID source) is front-loaded, and the return/polling behavior is stated succinctly.

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

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

For a mutation tool with no output schema and no annotation detail, the description covers the essential flow: source IDs, invoke, poll. The only minor gap is the lack of any guidance on the optional account parameter, though the name and sibling tools make it inferable.

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%, but the description adds crucial meaning to comment_ids by binding them to instagram_actions_list_comments and warning against official-media-comment IDs. However, the optional 'account' parameter is left entirely unexplained in both schema and description.

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

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

The description opens with a clear verb and resource: 'Like one or more comments.' It also distinguishes the required ID namespace from that of instagram_get_ig_media_comments, which directly prevents a common mix-up among sibling tools.

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

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

It explicitly states the required source of comment_ids ('MUST come from instagram_actions_list_comments') and the exclusion of IDs from instagram_get_ig_media_comments as invalid. This is clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds the specific fields returned and confirms it is a listing operation, which is consistent with the annotations. It does not disclose any additional behavioral traits such as pagination, ordering, or error cases, but the bar is lower given 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 a single, front-loaded sentence with no filler. It efficiently communicates the verb, resource, and output fields. Every word adds value, and the structure is ideal for quick parsing by an agent.

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, but the description omits the only parameter's purpose, which is a significant gap given the schema is entirely undocumented. Additionally, there is no output schema, so the description is the sole source of information about return values—it lists fields but does not clarify whether the response is a list or object, nor any filtering semantics. With complexity low, a complete description should have covered the parameter.

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 has one optional parameter 'account' with zero description coverage (0%), and the description makes no mention of this parameter whatsoever. Since the schema provides no meaning and the description does not compensate, the agent has no idea whether 'account' filters by ID, username, label, or something else. This is a critical gap.

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

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

The description uses a specific verb ('List') with a clear resource ('Instagram accounts connected to this install') and lists the fields returned (id, username, label). This unambiguously distinguishes it from sibling listing tools like instagram_actions_list_jobs or instagram_actions_list_comments, which target different resources.

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 what the tool does but gives no explicit guidance on when to use it versus alternatives. There are no mentions of prerequisites, context, or exclusion criteria. Usage is implied by the tool's obvious purpose, but the description does not direct the agent to consider other account-related tools or explain how to select this one.

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 convey readOnly, idempotent, and non-destructive behavior. The description adds meaningful behavioral context beyond this: it returns a job_id and instructs polling instagram_actions_get_job_status, and it reveals the ID format mismatch with the official API. This gives the agent important operational expectations.

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 earning its place: the core operation, the critical ID compatibility detail, and the job-polling requirement. The most important information is front-loaded, with no redundant 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?

Given there is no output schema, the description adequately explains what the agent receives (comment_id and job_id) and what to do next (poll instagram_actions_get_job_status). It does not elaborate on the 'account' parameter, which is a minor completeness gap for a tool with only two parameters.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies that the 'posts' parameter accepts URLs or shortcodes, which adds meaning to the otherwise bare array field. However, the optional 'account' parameter is not explained at all, leaving a gap for one of the two 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 states a specific action ('List the comments on a post'), identifies the resource ('a post, addressed by URL or shortcode'), and provides a concrete behavioral differentiator: it returns comment IDs in the form that instagram_actions_like_comment accepts and explicitly warns that the official API returns a different ID. This is a clear, distinguished purpose.

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 how to address posts and why this tool is useful: it produces comment IDs compatible with instagram_actions_like_comment, unlike the official API. It does not explicitly name alternative sibling tools or state when not to use it, but the ID compatibility note effectively routes agents to this tool over the official endpoint.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful scope context like 'recent' and 'connected account,' but does not mention pagination, time range, or what the returned list contains.

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 front-loaded sentence with no wasted words. It states the primary action, scope, and optional filtering in a highly readable order.

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 list operation with strong annotations, the definition is minimally adequate. However, there is no output schema, 'recent' is vague, and the account parameter is underspecified, so an agent may not know how to scope or paginate the request.

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 clarifies that status acts as an optional filter, which maps to the enum values, but it leaves the account parameter entirely unexplained and does not clarify its relationship to 'the connected account.'

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

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

The description states a specific verb and resource: 'List recent action jobs for the connected account.' It also distinguishes this from the sibling tool instagram_actions_get_job_status, which focuses on fetching a single job's status rather than listing jobs.

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 the tool: when you need a list of recent action jobs, optionally filtered by status. It does not explicitly name alternatives or exclusions, but the purpose is specific enough to imply the appropriate use case.

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 destructiveHint=false, so the description adds value by reinforcing 'does not mark as seen' (a behavioral guarantee beyond read-only) and by disclosing the return mechanism (job_id vs inline based on wait). No contradiction with annotations is present. The behavioral disclosure is clear and non-redundant.

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, well-structured sentence that front-loads the core action and scope, includes the key behavioral caveat, and discloses the return behavior. Every phrase earns its place with no fluff, making it easy to parse quickly.

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 listing tool, the description covers the main action and return format, but it omits details about the account parameter and does not clarify the expected format for target (e.g., username vs ID). Given that there is no output schema and no parameter descriptions in the schema, the lack of parameter guidance leaves the agent with reasonable but incomplete information for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate for all three parameters. It indirectly explains 'target' via 'a specific user's' and mentions 'wait' in the return context, but it never explicitly describes the account parameter or provides clear semantics for each parameter. The description falls short of giving the agent enough detail to correctly populate all inputs, especially 'account'.

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

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

The description states a specific verb ('List') and resource ('a specific user's currently available stories'), and explicitly notes it does not mark stories as seen, distinguishing it from tools like instagram_mark_seen and instagram_actions_view_story. This gives an agent a precise understanding of the tool's purpose without needing to infer from the name.

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 implies the use case: when you want to list stories without affecting seen status. It also explains the wait parameter behavior ('Returns a job_id (or the result inline when wait=true)'), which guides how to request synchronous vs asynchronous results. However, it does not explicitly name sibling tools as alternatives, relying on the read-only note to route usage.

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

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

Beyond the annotations, the description discloses that the tool is a workaround, returns a job_id (implying async execution), and has a low daily cap. This is useful additional context. It does not explain what happens if the target has already messaged the account or how authentication is handled, but the annotations already cover the read-only/destructive profile.

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 sentences with no wasted words. The critical qualifier 'FIRST' is front-loaded, and the one-recipient limit, low cap, and return value are all included efficiently.

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 core use case, constraints, and output are covered well enough for a simple tool. However, with no output schema and no parameter descriptions, the lack of guidance on account selection, dry_run behavior, and expected target format leaves meaningful gaps for an agent trying 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?

Schema description coverage is 0%, so the description carries the burden of explaining parameters. While 'target' and 'text' are inferable from 'send message,' the description never clarifies 'account' or 'dry_run', and it does not explicitly map 'one recipient per call' to the target parameter.

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

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

States a specific verb and resource: sending the first direct message to a user who has never messaged the account. The qualifier distinguishes this from ordinary messaging, and the note about the official API adds a clear differentiator. Even without naming a sibling, an agent can understand exactly what this tool is for.

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

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

Provides clear eligibility criteria: use for someone who has never messaged this account, and the official API cannot do this. It also adds concrete constraints like one recipient per call and a low daily cap. It does not explicitly name an alternative such as instagram_send_text_message for existing conversations, so it stops short of a full when/when-not comparison.

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 convey that this is mutating (readOnlyHint=false) and non-idempotent. The description adds that the operation can cover multiple users and returns a job_id, implying asynchronous processing. It does not disclose permission needs, failure modes, or what the job_id should be used for, beyond the sibling name get_job_status.

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 short sentences with the primary action and return behavior front-loaded. There is no redundant wording, and the core semantics are immediately scannable.

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 bulk unfollow tool, the description covers the main action and the job_id response. It is not fully complete, however, because it omits the account parameter's meaning and provides no guidance on job-status continuation or edge-case behavior, while the schema itself offers zero parameter documentation.

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

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

Schema description coverage is 0%, so the description must explain both parameters. It adequately clarifies targets as '@username' strings, but it never explains the 'account' parameter, leaving which Instagram identity performs the unfollow unclear. An agent would need to infer this from sibling tools or the schema name.

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 gives a specific action verb ('Unfollow'), a resource ('Instagram users'), the input convention ('by @username'), and the supported scale ('one or more'). It is readily distinguishable from siblings such as instagram_actions_follow and instagram_actions_like.

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 intended use is implied by the action word 'Unfollow', so an agent can tell when to select it. However, it does not explicitly contrast with instagram_actions_follow, mention already-unfollowed targets, indicate account selection requirements, or suggest following up on the returned job_id.

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

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

The annotations provide no strong hints beyond false flags, so the description carries the burden. It discloses the key side effect (marking stories as seen) and notes that the call returns a job_id, implying an asynchronous operation. It does not cover failure modes or rate limits, but the essential behavior is clear.

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

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

Two tight sentences with no filler. The core action is front-loaded, and the special-case behavior and return value each earn their 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 adequate for a simple tool but leaves material gaps: it does not explain the `account` parameter, the format of values in `targets`, or how to follow up on the returned `job_id`. Given the absent schema descriptions and output schema, these omissions make first-time invocation uncertain.

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

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

The schema has zero parameter descriptions, so the description must compensate. It explains `targets` well (one or more profiles, omit for home tray), but leaves `account` unexplained and does not state the expected format for profile identifiers. This is only partial parameter 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 names a concrete action ('Watch (mark as seen)') and a specific resource ('the stories of one or more profiles'), and also covers the home-tray variant. This clearly distinguishes it from sibling tools like instagram_actions_list_stories or instagram_mark_seen.

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 an explicit usage condition: omit `targets` to watch the home tray. This helps an agent decide between the two main invocation modes, though it does not name alternatives or exclusions among sibling 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?

Adds valuable behavioral context beyond annotations: the tool creates a draft container, imposes Instagram's 2-10 media item limit, warns about 24-hour expiration, and supports batched execution via plural ids. Annotations only indicate readOnly=false and idempotent=false, so this description meaningfully informs the agent about lifecycle and batching 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?

Three tightly packed sentences, each earning its place: first states purpose, second states critical Instagram constraints and expiration policy, third notes bulk execution. The most important information is front-loaded, and 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?

Given 13 parameters, no output schema, and no description coverage in the schema, the description should explain the overall workflow and key parameters much more thoroughly. Missing details include how children/media inputs relate to each other, what the response contains (creation_id), how share_to_feed behaves, and how bulk execution differs from single-mode execution. The provided constraints are useful but not sufficient for safe invocation.

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

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

Schema description coverage is 0%, so the description must compensate for the 13 undocumented parameters. It only touches on 'multiple images/videos' and mentions ig_user_ids and location_ids for bulk support. It does not explain parameters such as children, child_image_urls, child_video_files, share_to_feed, account, or graph_api_version, leaving significant gaps in parameter understanding.

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: 'Create a draft carousel post with multiple images/videos before publishing.' It clearly distinguishes this tool from publishing tools like instagram_post_ig_user_media_publish by emphasizing 'draft' and 'before publishing.' The carousel scope is explicit, leaving no ambiguity about what the tool does.

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

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

Provides clear operational constraints: carousels must have 2-10 media items and container creation_ids expire in under 24 hours, so publish promptly. This gives an agent strong context for when to use the tool and what follow-up timing is required. It does not explicitly name sibling alternatives or exclusions, but the 'before publishing' phrasing implies the workflow direction.

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. The description adds meaningful context beyond these: permission errors for personal accounts and eventual consistency for recently sent/received messages. This goes beyond the structured annotations and helps an agent anticipate non-success outcomes.

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 paragraphs with no redundancy. The purpose is front-loaded, followed by requirements and a timing note, then bulk support at the end. The structure is logical and efficient, though it could be made even tighter by merging the bulk note into the first paragraph.

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 get tool, it covers key operational constraints: permissions, timing, and bulk capabilities. However, it is vague about what 'details' actually includes (only 'participants, etc.') and does not explain the purpose of account or graph_api_version. With no output schema, it could briefly state that results include conversation metadata, but overall it is adequate for a simple retrieval 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?

Schema description coverage is 0%, so the description must compensate. It explicitly references conversation_ids for bulk usage, but only implies conversation_id as the singular target. It does not explain account or graph_api_version at all, leaving these parameters undocumented despite the lack of schema descriptions. Partial coverage is insufficient for a 4-parameter tool.

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 verb (get) and resource (a specific Instagram DM conversation), and mentions 'participants' as an example detail. It distinguishes from sibling list tools like instagram_list_all_conversations by emphasizing 'specific'. The use of 'etc.' is vaguely broad but does not obscure the core purpose.

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

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

Provides explicit requirements (Business or Creator account with messaging permissions), a timing note (messages may take a few seconds to appear), and bulk execution support via conversation_ids. While it does not name alternative tools, it implicitly tells agents when to use this tool (for a specific conversation) and when bulk support applies.

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 this is read-only, idempotent, and non-destructive. The description adds valuable behavioral scope by clarifying that only published media is supported and by disclosing bulk execution via ig_media_ids. This goes beyond the structured annotations without contradicting them.

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 appropriately brief and front-loaded with the core purpose, followed by the usage condition, scope caveat, and bulk support note. The only issue is that the caveat about unpublished containers appears truncated, but the visible text is otherwise efficient.

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

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

The description outlines what the tool returns and notes bulk support, but with no output schema and no parameter descriptions, an agent still lacks enough detail to know how to request specific fields or whether account/graph_api_version are needed. It is adequate for tool selection but not fully complete for invocation.

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

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

Schema description coverage is 0%, so the description needed to compensate by explaining parameters. It only mentions ig_media_ids for batched execution and indirectly references ig_media_id as a specific post ID. The fields, account, and graph_api_version parameters are not explained, leaving significant ambiguity for constructing a request.

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 a specific verb and resource: getting a published Instagram Media object (photo, video, story, reel, or carousel). It also indicates the scope, 'published media only,' and describes the kind of data returned. It does not explicitly name a sibling tool to differentiate from, so it falls just short of a 5.

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

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

It states when to use the tool: when retrieving detailed information about a specific Instagram post. It also gives an explicit exclusion: this action is for published media only, with a reference to unpublished container IDs. It does not name alternative sibling tools, so the guidance is clear but not fully comprehensive.

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context beyond those hints: it mentions cursor-based pagination, describes that an empty data array indicates something about the response, and notes bulk support via ig_media_ids. This is meaningful added 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 reasonably concise and front-loaded with the purpose, but it suffers from an incomplete sentence ('An empty data array in the response indicat…'), which reduces clarity and structural quality. It also mixes pagination, response-shape, and bulk support without clear organization.

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 has 8 parameters, no output schema, and no enum constraints, so the description needs to provide substantial guidance. It covers purpose, pagination, and bulk execution, but it leaves most parameter semantics unexplained, lacks return-format detail beyond the truncated empty-array note, and does not specify account or authentication requirements. This is not enough for reliable invocation.

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

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

Schema description coverage is 0%, so the description must carry the burden of parameter explanation. It only adds context for pagination ('cursor-based pagination') and the bulk 'ig_media_ids' parameter. The roles of after, before, limit, fields, account, and graph_api_version remain undocumented, leaving an agent to guess at required values and formats.

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 verb ('retrieve') and resource ('comments on an Instagram media object'), and enumerates the object types covered (post, photo, video, carousel). It does not explicitly distinguish itself from sibling tools like instagram_actions_list_comments, but the purpose is unambiguous.

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

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

The description includes an explicit 'Use when you need to fetch comments from a specific Instagram post...' clause, which gives clear context for when to invoke the tool. It does not mention when to prefer alternative tools, but the usage trigger is specific enough to route an agent correctly.

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 readOnly/idempotent safety, so the description adds value by disclosing the response path ('read result.result.data') and warning that availability depends on media type and metric. It also reveals bulk execution behavior via ig_media_ids, which is not visible in 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 stated in the first sentence and each subsequent line adding a specific operational detail. The formatting is slightly dense, but 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?

There is no output schema, so the response-path note ('read result.result.data') is helpful, and the bulk-support mention adds coverage for the batched variant. However, several parameters remain undocumented in a tool with 7 inputs, and the description does not clarify the shape of the insights data beyond pointing at result.data.

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 0% schema description coverage, the description must compensate for undocumented parameters, but it only explains metric (with accepted values) and bulk support via ig_media_ids. period, account, breakdown, ig_media_id format, and graph_api_version are left entirely unexplained, leaving an agent to guess at their semantics.

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

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

The description opens with a specific verb and resource, 'Read media insights,' which clearly identifies this as a per-media analytics tool. It further enumerates the exact metrics available (views, reach, saves, shares), distinguishing it from siblings like instagram_get_ig_media (media content) and instagram_get_user_insights (account-level analytics).

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 intended use is implied by the resource name and the metric list, but the description never explicitly states when to choose this over get_user_insights or get_ig_media. The bulk-support note provides some contextual guidance for batched calls, yet there are no exclusions or alternative-routing hints.

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 a non-obvious response nesting detail: 'read result.result.data and result.result.paging (not result.data)'. It also clarifies that null engagement fields mean unavailable, not zero, which is a meaningful semantic caveat. Bulk execution behavior is disclosed as well, adding value beyond the readOnly/idempotent 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: a one-line purpose, a single sentence with a critical parsing caveat, and one sentence on bulk support. No filler or redundant repetition of the tool name or annotations.

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 12-parameter tool with no output schema and no parameter descriptions, the description is incomplete. It provides one important response-structure note and bulk-support awareness, but does not explain most parameters, the shape of `data`, pagination mechanics, or error conditions. An agent would likely need to infer or experiment to form a correct request.

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% and there are 12 parameters, so the description must compensate heavily. It only adds meaning for `ig_user_ids` and `auto_resolve_fb_page_ids` via the bulk-support note, and indirectly references paging. The other parameters—`account`, `ig_user_id`, `fields`, `limit`, `since`, `until`, `before`, `after`, `graph_api_version`, `auto_resolve_fb_page_id`—are left entirely unexplained.

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 'List account media' states a specific verb and resource, making the core function clear. It does not explicitly contrast with sibling `instagram_get_ig_media`, but 'list' versus single-media retrieval is inferable from the tool name and 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?

The description gives explicit guidance on an alternative: 'use media insights for saved, shares and views' when engagement fields are null. It also highlights bulk support with `ig_user_ids` and `auto_resolve_fb_page_ids`, clarifying when batched execution is appropriate. It does not exhaustively map all sibling alternatives, but the guidance provided is actionable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral nuance: followers_count and follows_count are only returned for the user's own profile (ig_user_id='me'), and bulk execution is supported. This goes beyond annotations, despite being truncated.

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 relatively concise and front-loaded with the main purpose, but the sentence about follower counts is cut off mid-phrase ('For other accounts, follower/…'), making the text incomplete and structurally broken. This undermines clarity and professionalism.

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 4 parameters and no output schema, the description should fully specify how to invoke the tool. It covers the primary ID and bulk patterns but omits semantics for 'account' and 'graph_api_version', and does not describe the return payload structure. The truncated note also leaves uncertainty about follower count behavior for non-own accounts.

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 explain all parameters. It covers ig_user_id ('me' or numeric ID) and ig_user_ids (bulk), but does not explain 'account' or 'graph_api_version', leaving ambiguity about their purpose and expected values. This partial compensation is insufficient for full agent guidance.

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 'Get Instagram Business Account info including profile details and statistics.' The verb 'get' and resource 'account info' are specific. It distinguishes from siblings like instagram_get_user_insights by focusing on profile details rather than insights, though it does not name alternatives explicitly.

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 explicit usage scenarios: using 'me' for the authenticated account or a numeric Business Account ID for managed accounts, and mentions bulk support via ig_user_ids. This gives clear contextual guidance on parameter selection, though it does not state when not to use the tool or exclude siblings.

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 bar for extra disclosure is satisfied by the description's added context: the exact response path, empty-array semantics, the lack of an intrinsic follower-count restriction, and bulk support. These go beyond the structured 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?

The description is compact and front-loaded: the core read action and response location appear first, followed by the critical empty-array caveat and bulk-support note. Every sentence adds information 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 an 11-parameter tool with no output schema and no parameter descriptions, the description is too sparse. It covers important caveats and bulk behavior but omits guidance on metric/period combinations, parametrization choices, and expected response shape, so an agent could struggle to construct a correct 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?

With 11 parameters and 0% schema description coverage, the description needed to explain most parameters, but it only clarifies ig_user_ids for bulk support. The many other parameters (since, until, metric, period, breakdown, metric_type, graph_api_version) receive no semantic help, leaving the agent to infer from names and enums.

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 says 'Read account insights', a specific verb and resource, and clarifies where the data appears ('at result.result.data in REST'). It distinguishes account-level insights from media insights, though it does not explicitly name the sibling tool it differs from.

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 provides useful usage context: bulk execution via ig_user_ids and the caveat that an empty data array means unavailable, not zero. However, it gives no explicit guidance about when to prefer this over sibling tools like instagram_get_ig_media_insights, leaving some routing to inference.

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

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

Annotations already declare read-only and idempotent behavior, and the description adds substantial context beyond them: permission requirements, the nested data.data response structure, the legitimate empty-data case, and bulk execution via user_ids and ig_user_ids.

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 core purpose is front-loaded, and each subsequent sentence adds a distinct, useful detail such as auth requirements, response nesting, or bulk support. It is dense but not padded.

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

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

The description gives strong auth and response-shape guidance, but for a 9-parameter tool with no output schema it remains incomplete. Pagination, account/platform selection, and graph API versioning are left undocumented.

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% across 9 parameters. The description only clarifies user_ids and ig_user_ids for batched execution, while after, limit, account, platform, ig_user_id, and graph_api_version remain semantically unexplained.

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 all Instagram DM conversations for the authenticated user.' This clearly distinguishes it from siblings like instagram_get_conversation (single conversation) and instagram_list_all_messages (messages rather than conversations).

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

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

Provides clear usage context by stating the Business/Creator account requirement with messaging permissions and warning that personal accounts return empty results. It lacks explicit alternative routing, but the guidance is concrete enough to prevent common misuse.

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 tool read-only, idempotent, and non-destructive. The description adds substantial runtime context: the account-type requirement, the double-wrapped data.data response shape, the possibility of empty text fields for attachment-only messages, and bulk execution support. This goes well beyond the structured 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?

Two short paragraphs with no filler, opening with the core operation. The account prerequisite, response-shape caveats, and bulk note are all relevant and 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?

Covers the critical account prerequisite and a notable response-shape quirk, which is genuinely useful. However, with no output schema and 0% parameter coverage, it omits pagination/after/limit semantics, error behavior, and detailed field expectations. It is adequate as a minimum viable description but has clear gaps.

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

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

Schema description coverage is 0%, so the description carries the full burden of explaining parameters. It only clarifies conversation_id implicitly and conversation_ids for bulk execution; after, limit, account, and graph_api_version remain unexplained. Most parameters are still under-specified for an agent.

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 operation: listing all messages from a specific Instagram DM conversation. It is clearly distinguished from conversation-listing or messaging siblings in general terms, but it does not explicitly differentiate from instagram_get_conversation. The account-type qualifier adds useful 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?

Explicitly states the prerequisite (Business or Creator account with messaging permissions) and warns that personal accounts return empty results, which tells agents when not to use it. The bulk-support note indicates a batch use case. It does not name an alternative tool for single-conversation retrieval, so it lacks explicit exclusion routing.

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 that marking as seen 'is visible to the other party and changes inbox read state,' which is valuable behavioral context beyond the annotations. It also positions the operation as requiring explicit approval. The 'IMPORTANT LIMITATIONS…' section is left unfinished, which prevents a higher score.

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 first sentence is direct and front-loaded, and the bulk note is useful. However, the dangling 'IMPORTANT LIMITATIONS…' heading with no actual limitations listed weakens the structure and makes the description feel incomplete.

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 six parameters, no output schema, and 0% schema description coverage, the description leaves important gaps: the actual limitations are missing, several parameters are unexplained, and there is no indication of the response shape or failure behavior. This is not enough for an agent to call the tool with full confidence.

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 0% schema description coverage, the description must compensate. It adds meaning to the bulk parameters ('accepts ig_user_ids, recipient_ids for batched execution') and implies recipient_id is used for single-user flows. But it does not explain account, graph_api_version, or the relationship between ig_user_id and recipient_id.

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: 'Mark Instagram DM messages as read/seen for a specific user.' It also explains the mechanism ('Sends a mark_seen sender action') and clearly separates this from message-sending and viewing 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?

It gives clear context for when to use the tool and adds an important condition: 'use with explicit user approval in automated or bulk flows.' Bulk versus single-recipient usage is also addressed. However, it does not explicitly name alternative tools 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.

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

Annotations already indicate readOnly=false, destructive=false, and idempotent=false. The description adds valuable behavioral detail beyond this: the 300-character limit, hashtag/URL caps, all-caps prohibition, and bulk support via ig_comment_ids. This helps the agent understand constraints that are not otherwise visible.

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 primary purpose. The content constraints and bulk support are presented in an organized manner without unnecessary fluff. Every sentence adds useful 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?

The description covers the core action, constraints, and bulk mode, but does not explain the account parameter or graph_api_version, which an agent may need to correctly invoke the tool. There is no output schema, so return value behavior is also unspecified. Overall it is adequate but has notable gaps.

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

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

Schema description coverage is 0%, so the description must carry the full burden of explaining parameters. It does provide meaning for message (content constraints), ig_comment_id (implicitly), and ig_comment_ids (bulk support), but leaves account and graph_api_version entirely unexplained. This is a significant gap given the schema provides no 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 a specific action ('create a reply to an Instagram comment') and specifies the resource (a comment on an Instagram post). It also distinguishes this tool from sibling tools like liking or listing comments by stating the intended use case.

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: use when replying to a specific comment on a Business or Creator account's post. It also lists content constraints. However, it does not explicitly mention alternatives or when not to use the tool, so it falls short of a 5.

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

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

Annotations are neutral (no readOnly, idempotent, or destructive hints), so the description carries the transparency burden. It discloses that the tool creates a container rather than publishing, and it mentions batch execution. It does not clarify side effects, permissions required, or what the created container returns, which is relevant given no output schema. This is adequate but not rich.

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 short, front-loaded with the core purpose, and avoids unnecessary repetition. The two-step process explanation and bulk support note are useful and earn their place. A slightly more structured layout would improve scannability, but it is already efficient.

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

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

Given the tool's complexity (20 parameters, nested objects, enums, no output schema), the description is not complete. It explains the high-level workflow but omits critical operational details such as which parameters are mutually exclusive, how carousel children should be provided, how media_type relates to other fields, and what the container response contains. The two-step context is helpful but insufficient 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 input schema has 20 parameters with 0% description coverage, so the description must compensate. It names only ig_user_ids and location_ids for bulk support, and vaguely alludes to images, videos, Reels, and carousels. Most parameters such as image_file, video_file, children, media_type, share_to_feed, and cover_url receive no semantic explanation or usage guidance.

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 verb and resource: create a media container for Instagram posts, with explicit mention of image, video, Reel, and carousel container types. It also distinguishes itself from the publishing step by naming the media_publish endpoint. However, it doesn't explicitly differentiate from the sibling tool instagram_create_carousel_container, which likely overlaps for carousel use cases.

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 usage context by explaining this is the first step in Instagram's two-step publishing process and explicitly directs the agent to use the media_publish endpoint afterward. It also mentions bulk support with ig_user_ids and location_ids. It does not, however, specify when to prefer this tool over instagram_create_carousel_container for carousels.

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 minimal annotations, it discloses that the tool blocks while the container finishes processing and that Instagram imposes a rolling 24-hour rate limit. It also notes batch execution. It doesn't describe duplicate-post side effects, but the provided behavioral details are substantive.

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 text is only three sentences and front-loads the core purpose. However, the rate-limit sentence is cut off ('via IN…'), making the description incomplete and slightly undermining its structure.

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 tool with no output schema and no schema descriptions, this is under-specified: required parameter semantics, return value, and prerequisite 'create container first' are missing. The rate-limit and wait behavior help but don't make it callable without guessing.

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 0% schema coverage, the description was expected to compensate, but only ig_user_ids and creation_ids are named. The required creation_id, account, ig_user_id, max_wait_seconds, poll_interval_seconds, and graph_api_version are left unexplained.

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 ('publish') and resource ('media container to an Instagram Business account'), making the action unambiguous. The name mirrors the Instagram media_publish endpoint, and the wording distinguishes it from the sibling container-creation tool.

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

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

No explicit when-to-use or alternative routing appears; it doesn't say 'use after creating a container' or contrast with instagram_post_ig_user_media. The mention of bulk support is a capability, not a usage condition.

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 beyond the sparse annotations by disclosing that each send modifies inbox state and by warning about bulk/automated sends. This is meaningful behavioral context, though it omits further details like auth requirements or rate limits.

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

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

The description is compact and front-loaded: purpose first, then a behavioral caution, then bulk support. Every sentence adds information, 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?

For a mutating tool with 7 parameters, no output schema, and no parameter documentation in the schema, the description is too thin. It omits return behavior, account/version semantics, and how the bulk ID arrays interact with the required recipient_id parameter.

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 0% schema description coverage, the description must compensate, but it only explains ig_user_ids and recipient_ids in the context of bulk execution. It leaves account, ig_user_id, graph_api_version, and the relationship between recipient_id and the bulk ID fields unexplained.

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 ('Send an image via Instagram DM to a specific user') and a clear resource, making the tool's core purpose obvious. It does not explicitly contrast itself with instagram_send_text_message or instagram_actions_send_message, but the image-vs-text distinction is implicit.

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

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

It provides useful context about when it is acceptable to use the tool ('avoid bulk or automated sends without explicit user approval') and notes bulk support. However, it gives no explicit guidance on when to choose this tool over the sibling text-message or generic send-message 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 the sparse annotations, the description discloses the account-type permission, the inability to initiate new threads, a specific failure subcode, and an explicit no-retry rule. It also reveals bulk execution behavior, which is valuable for an agent deciding how to invoke and react to the tool.

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

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

The description is compact and well-structured: action first, then constraints, then failure handling, then bulk support. Every sentence adds operational value and no filler is present.

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?

It covers prerequisites, error handling, and bulk support, but for a 9-parameter tool with no output schema it does not clarify parameter relationships or what a successful or bulk call returns. It is sufficient for basic use but incomplete for advanced parameter selection.

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 carries the parameter-documentation burden. It clarifies only `text`, the existing-conversation context, and the bulk array parameters; it leaves `ig_user_id` vs `recipient_id`, `account`, `graph_api_version`, and singular `reply_to_message_id` ambiguous. This is not enough for a 9-parameter tool.

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 ('send a text message'), a specific target ('Instagram user via DM'), and a critical scope constraint ('existing conversation'). This clearly distinguishes the tool from media-sending or thread-initiating 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?

It provides strong when-to-use guidance: existing conversation, Business/Creator account, messaging permissions, and bulk usage. It also gives clear when-not-to-use signals (cannot initiate new threads, do not retry error_subcode 2534022). It does not name a specific alternative tool for initiating new DMs, so it misses a full 5.

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

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

Beyond the annotations, the description discloses important behaviors: invoke runs an MCP even when it is not installed, does a one-off run without adding the MCP to the toolkit, returns a connect link when credentials are needed, returns a checkout/top-up link when payment is needed, and requires workspace owner/admin for write operations. The description enriches the annotations and does not contradict them.

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 identity and the core flow, and nearly every sentence carries useful guidance. However, it is one dense, wall-of-text paragraph with mixed language ("pontualmente") and heavy inline emphasis, which makes the many action alternatives hard to scan and parse.

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 23-parameter, 14-action facade with no output schema, the description is remarkably complete: it covers the core flow, one-off invoke semantics, auth/credential/payment behavior, permission requirements, installed flags, the prompt library, and most action outcomes. The main gaps are the resume action and return-shape details for a few actions, but the overall guidance is sufficient for correct invocation in most cases.

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 0% schema description coverage, the description does a lot of compensating work: it maps action values such as search, describe, invoke, install, list_tools, publish_prompt, and explains tool_id, arguments, and prompt-related intent. However, several parameters and enum actions remain unexplained, including resume, limit, immediate, tier_slug, cancel_reason, report_context, conversation, request_name, and request_details, leaving agents under-specified for those paths.

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 tool as the official mcp.ai marketplace: the in-platform catalog of MCPs/tools and the way to run them. It states the core discovery→describe→invoke flow, distinguishes the prompt-library subdomain from the MCP flow, and makes it clear this is a marketplace orchestrator rather than one of the sibling calculator/authenticate tools.

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

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

The description gives explicit when-to-use guidance: use install only to make an MCP permanent, prefer invoke for one-off use, use list_tools to see what is callable now, use subscribe/cancel for billing, and use request_mcp when nothing fits. It also explains what to do when invoke returns a connect link or checkout link, including retry behavior.

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

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

Annotations already carry the safety profile with idempotentHint=true and destructiveHint=false. The description adds that conversation data is needed for reproduction, which is useful context. However, it does not disclose what happens after submission, such as whether a ticket is created or whether the report is asynchronous, though the annotations lower the burden.

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 consists of two tight sentences: the first states the purpose, the second gives the key usage instruction. There is no filler, repetition, or irrelevant 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 simple three-parameter reporting tool with annotations already covering idempotency and destructiveness, the description is mostly sufficient. The main gaps are the unexplained `context` parameter and the absence of any indication of what the response or outcome will be, though no output schema is expected.

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 for undocumented parameters. It only clarifies the `conversation` parameter via 'conversation array with recent messages,' leaving the required `message` and optional `context` undefined. The agent must guess at their intended content.

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 the verb 'Report' and explicitly enumerates three targets: 'bug, missing feature, or send feedback'. This makes the tool's purpose unmistakable and easily distinguishable from the sibling calculo_* and authentication tools, which serve entirely different functions.

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 establishes a clear context: use when a user reports a problem or wants to provide feedback. It also adds practical guidance to 'Include the conversation array with recent messages for reproduction.' It does not name alternatives, but none of the sibling tools overlap with bug reporting, so exclusions are unnecessary.

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

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

The annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows this is a safe, non-mutating call. The description adds little beyond that—it names the output as versions but doesn't specify the format (e.g., semver strings, JSON object) or whether the output is human-readable. Since the annotations carry the safety profile, a 3 is appropriate.

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 sentence of 9 words, front-loading the action ('Show') and the object ('version'). There is zero waste, and it fully conveys the tool's purpose within its scope. This is a model of conciseness.

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

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

For a zero-parameter, read-only, idempotent tool with no output schema, the description is nearly complete. An agent can confidently invoke it without additional context. The only minor gap is that the return format is unspecified, but since there is no output schema, a brief note on the output structure (e.g., 'returns a plain-text summary') would elevate completeness. Still, the description is sufficient 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 tool has zero parameters, and the schema coverage is 100% (no properties). The description doesn't need to explain parameters. The baseline for zero-parameter tools is 4, and the description is consistent with that—it correctly implies that no input is required.

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's purpose: 'Show the current MCP platform and adapter versions.' This is a specific verb-resource pair that distinguishes it from sibling tools, which are all calculation or authentication tools. It could be slightly more explicit about what 'show' returns (e.g., a text summary vs. structured data), but the resource is unambiguous.

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

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

The description implies that this tool is for checking version information, which makes sense in contexts where an agent needs to confirm platform/adapter versions before proceeding. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention whether version information is needed for authentication or compatibility checks. Given the sibling tools are all calculations, the usage context is reasonably clear, but not explicitly delineated.

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=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate safety. It adds value by detailing what kind of state is returned, including connection status and account bindings, which helps the agent understand the tool's informational scope.

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

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

A single tightly packed sentence with the main action front-loaded, followed by a colon-delimited list of return contents. Every phrase earns its place with no repetition 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 zero-parameter, read-only introspection tool, the description fully covers what the agent needs to know before calling: what information it will receive. No output schema exists, but the description essentially provides a light output contract by enumerating the returned components.

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 is empty with zero parameters, and schema description coverage is 100%, so the description has no parameter burden. Per calibration, zero-parameter tools receive a baseline of 4; the description's output-focused content is more than sufficient.

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 ('Returns') and resource ('current toolkit state'), then enumerates exactly what is included: installed MCPs, connection status, connected accounts, and catalog tool counts. This is specific enough to distinguish it from computational siblings like calculo_* and action tools like authenticate or connect.

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 conveys that this is the tool to call when an agent needs an overview or snapshot of the toolkit's current state. It does not explicitly list exclusion criteria or name alternatives such as show_version, but the context is clear enough for routine selection.

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