Adeli

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

Goes far beyond the annotations: it discloses permance ("Meta has no API to close or delete an ad account"), a quota ("a portfolio may only hold a few"), field immutability (currency and time zone cannot be changed later), and exact idempotency semantics (a repeated key returns the first result). This is behavior an agent could not infer from readOnlyHint/destructiveHint/openWorldHint.

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

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

Three sentences, each carrying distinct high-value information (scope, permanence/confirmation, idempotency), with the action front-loaded. No filler or restatement of the title.

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

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

Adequately complete for a permanent, irreversible create with no output schema: the agent learns the required inputs' source, the confirmation requirement, and retry safety. It omits what the call returns (e.g., the new account id), which is a minor gap since no output schema exists.

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 only 43% schema description coverage the description must compensate, and it does for the highest-risk fields: idempotencyKey retry behavior, currency/timezone immutability, and the source of businessId. It does not add meaning for name or the accountId/profileId defaults, leaving those to the schema.

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

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

States a specific verb+resource ("Create an ad account") and scopes it precisely to "a Business portfolio from ads_list_businesses," naming the sibling that supplies the required businessId. This cleanly distinguishes it from ads_update_account, ads_get_account, and ads_list_accounts.

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

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

Gives clear prerequisites and a strong operational directive: fetch the businessId via ads_list_businesses and "confirm every field with the user first." It stops short of an explicit when-not rule, but the usage context is unambiguous.

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

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

Annotations only declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description goes well beyond that: resources are created PAUSED, no spend occurs until a separate activation call, and a repeated idempotencyKey returns the first result rather than duplicating. These are non-obvious behaviors an agent must know before invoking a mutating 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?

Three sentences, each carrying distinct load: what gets created and its state, the activation dependency, and the retry/units semantics. Front-loaded with the creation outcome and zero 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 9-parameter mutating tool with no output schema, the description covers the crucial behavioral facts and notes that a preview is returned, so return-value ambiguity is partly addressed. The remaining gap is the undocumented parameters, which the description does not backfill.

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

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

Schema description coverage is only 33%, so several parameters (adAccountId format, pagePostId, startDate/endDate, campaignName) carry no explanation anywhere. The description compensates for dailyBudget ('whole currency units') and confirms idempotency semantics, but that leaves most of the required parameters undocumented. Partial compensation merits a 3.

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

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

States a specific verb and resource chain: turn a Page post into a campaign, ad set and ad. It is immediately distinguishable from siblings like ads_create_account (creates an account) and ads_set_status (changes state), so an agent can route correctly without opening a schema.

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

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

Explicitly names the follow-up tool and condition for activation ('Nothing spends until ads_set_status sets it ACTIVE'), which tells the agent when this tool's job ends. It also covers the retry path via idempotencyKey. It stops short of naming when NOT to use it versus a generic campaign creation path, so it isn't a full 5.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known; the description adds real value beyond that by disclosing the cascade (all ad sets and ads are deleted), the irreversibility, and the immediate delivery stop. It stops short of stating permission requirements or whether the deletion can be recovered.

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

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

Three tight sentences with zero filler: scope first, then the irreversible/immediate effect, then the safety instruction. 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?

For a destructive mutation with no output schema, the description covers scope, irreversibility, side effects, and the required user confirmation, and annotations carry the safety hints. It could still say whether permissions are needed or whether any recovery is possible, so it is not fully complete.

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

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

Schema description coverage is 75%, with adAccountId carrying no description in either the schema or the description. The description implies campaignId comes from ads_get_tree and that the campaign should be confirmed by name, but adds no format or defaulting detail beyond the schema.

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

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

States a specific verb (delete), the exact resource (campaign) and its cascade scope (ad sets and ads), and ties the resource to its source tool ads_get_tree. An agent can distinguish this from ads_set_status or delete_comment without opening any schema.

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

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

Gives a workflow prerequisite (confirm the campaign by name with the user first) but never names when to prefer this over alternatives such as ads_set_status for pausing. Usage is implied rather than explicitly scoped.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and external-dependency context is covered. The description earns credit for non-obvious behavioral traits: it discloses that paymentMethod is null specifically when Meta withholds it, and that amounts are in whole currency units rather than cents. Neither of these is derivable from annotations or schema, which is genuinely useful. It stops short of describing staleness, caching, or error behavior, so it sits at a solid 3.

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

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

Two compact sentences, front-loaded with the primary action and resource, and every clause carries distinct information (returned fields, null semantics, currency units). 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 single-entity read with readOnly/openWorld annotations and no output schema, the description covers what is returned and two important data quirks. However it leaves the required adAccountId parameter completely undocumented in both description and schema, and gives no usage routing to the many similar sibling tools. Adequate but with clear gaps.

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

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

Schema coverage is 67%, so the schema already documents accountId and profileId with defaults; the description adds no parameter-level semantics. The third parameter, adAccountId, has no schema description at all and the description also says nothing about its act_<id> format or where it comes from. Baseline 3 with a partial gap that the description does not close.

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 clear verb+resource: 'Return one ad account' with a specific enumeration of returned fields (status, amount spent, spending limit, payment method presence). It distinguishes the single-account retrieval from the list-oriented siblings (ads_list_accounts, get_account) implicitly through 'one ad account', though it never names those 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?

No when-to-use guidance at all. It does not tell the agent how this differs from ads_list_accounts, ads_get_tree, ads_get_insights, or the generic get_account, nor does it state prerequisites such as needing an adAccountId obtained from list_accounts. The agent must infer usage entirely.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description usefully adds daily granularity and default-scope behavior, but with no output schema it never clarifies what 'performance' actually contains (metrics returned), leaving the agent guessing at the payload.

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

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

A single sentence, front-loaded with the primary purpose and granularity, with zero filler. Every clause earns its place.

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

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

For a moderately complex six-parameter read tool with no output schema, the description covers selection scope but says nothing about the return shape or what 'daily performance' fields an agent will get. Annotations cover safety, so it is adequate but leaves a meaningful gap.

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

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

Schema coverage is 83%, so the schema already documents since/until/objectId/accountId/profileId. The description only restates objectId's role ('or for one campaign, ad set or ad when objectId is given') and adds nothing about date-range or account resolution beyond what the schema provides. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Return daily performance') plus the granularity scope (account, campaign, ad set, or ad) and the condition that selects the finer granularity ('when objectId is given'). An agent can distinguish this from structural tools like ads_get_tree, though it doesn't name any sibling 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?

Implies usage context by describing the objectId drill-down and default account-wide scope, but gives no explicit when-to-use/when-not guidance and never contrasts with alternatives such as ads_get_tree or the platform-specific insights 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 readOnlyHint=true and openWorldHint=true, so safety and scope are covered. The description adds the useful behavioral fact that results are date-range scoped and carry spend/delivery metrics, but says nothing about result size, pagination, or rate limits, which matters for a tree that fans out to every ad.

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

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

A single front-loaded sentence with the resource first and the payload second. Every clause carries 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?

With no output schema, the description does the necessary work of naming what is returned (campaigns, ad sets, ads plus spend and delivery metrics), which is enough for an agent to call it correctly. It stops short of describing pagination or output shape for a potentially large tree, a minor gap given the read-only annotations.

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 80%, so the schema already documents since/until pairing rules, the 730-day cap, and the accountId default. The description only echoes the date-range concept and implies the account scope; it adds no syntax or defaulting detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Return an ad account's campaigns, ad sets and ads') and specifies the payload (spend and delivery metrics for the date range). This is clearly distinguishable from flat sibling reads like ads_get_account, though it does not name any sibling explicitly to sharpen the boundary with ads_get_insights.

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

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

The description implies the use case (fetching the full hierarchy with metrics for a period) but gives no explicit when-to-use guidance and never names an alternative such as ads_get_insights for metrics-only queries. An agent must infer the routing from the tool name and sibling list.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds real behavioral value beyond that: the reachability scope (direct or via Business portfolio) and the fact that returned adAccountIds are the input to all other ads tools.

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 zero filler. The core purpose is front-loaded and the downstream-usage note follows immediately.

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

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

With no output schema, the description usefully signals the identifier format returned (act_<digits>) and the discovery role of the tool. It omits pagination or result-shape detail, but the essential calling context is present.

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

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

Schema description coverage is 100% and both parameters (accountId, profileId) are documented in the schema with defaults. The description adds no parameter-level detail beyond noting adAccountId format, so the baseline 3 applies.

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

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

States a specific verb (List) and resource (Facebook ad accounts) with the scope qualification 'the connected Facebook account can reach, directly or through a Business portfolio.' This clearly separates it from ads_get_account and ads_list_businesses.

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 second sentence gives strong contextual guidance: every other ads tool needs an adAccountId obtained here, making this an upstream discovery call. It doesn't explicitly name a sibling alternative (e.g., ads_list_businesses) or state when-not to use it, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the useful scoping fact that results are limited to portfolios administered by the connected account, but says nothing about pagination, result shape, or auth/permission requirements beyond the connection.

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

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

Two short sentences with zero filler; the resource and scope come first and the relationship to ads_create_account is a genuinely load-bearing second sentence.

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, zero-required-param list tool with fully documented parameters and annotation-covered safety, this is nearly complete. The only real gap is the absence of return/pagination expectations, which matters slightly since no output schema exists.

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

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

Schema description coverage is 100% and both parameters (accountId, profileId) are already documented with defaults in the schema, so the description carries no additional parameter burden. It adds nothing beyond the schema, which is the expected baseline rather than a strength.

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 (List) and resource (Business portfolios) with an explicit scope qualifier: portfolios 'the connected Facebook account administers'. It also positions itself relative to ads_create_account, so an agent knows both what it returns and why it matters.

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 second sentence gives a concrete when-to-use trigger: call this before ads_create_account because ad accounts can only be created inside one of these portfolios. It does not, however, name ads_list_accounts as the distinguishing alternative or state any when-not 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the mode-dependent scope (forms vs submissions), but discloses nothing about pagination, permissions, or rate limits against a remote Facebook API, leaving it at a middling level.

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

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

Two short sentences, both front-loaded with the operative condition, and zero wasted words. Every clause carries a distinct piece of information.

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

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

With no output schema, the description captures the essential dual-mode behavior and the fact that results come from a connected Page/account. It omits pagination and result-shape detail, but nothing critical to invoking the tool is missing.

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

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

Schema coverage is 67% and notably formId has no schema description at all; the description supplies its meaning (selects submission-listing vs form-listing). accountId and profileId are already documented in the schema, so the description adds nothing there, keeping this just under full marks.

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 ... lead forms', 'list ... submissions') and clearly branches behavior on formId. It does not explicitly differentiate itself from any sibling, but no sibling in the list covers lead forms, so the risk of confusion is low.

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 two-sentence structure tells the agent exactly which mode to expect based on presence/absence of formId, which is the key usage decision. It stops short of naming alternatives or exclusions against other ads_* read tools, so it is not a full 5.

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

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

Annotations already flag the tool as destructive and open-world, but the description adds critical context beyond them: ACTIVE starts spending real money on the ad account and requires explicit user confirmation. This is exactly the kind of consequence disclosure an agent needs before invoking a financially risky mutation.

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

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

Two sentences, zero waste. The core action is front-loaded, followed immediately by the most important risk warning, making it easy to scan.

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

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

For a destructive 6-parameter tool with low schema coverage and no output schema, the description covers the critical safety angle but leaves parameter distinctions and alternative-tool guidance unaddressed. It is adequate to prevent reckless activation, but not complete for confident invocation across all 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 only 33%. The description reiterates the ACTIVE/PAUSED enum already present in the schema and hints that objectId may be an ad or ad set, but it does not explain the required adAccountId format (act_ prefix), how to choose objectId, or the role of optional campaignRecordId.

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: 'Set an ad or ad set to ACTIVE or PAUSED.' This is clear and actionable, but it does not differentiate the tool from siblings like ads_update_account or ads_create_campaign.

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 a strong prerequisite for ACTIVE ('never activate without the user's explicit confirmation of the budget and dates'), which implies when to use it. However, it gives no explicit guidance on when to choose this tool over sibling status-update or account-update tools.

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

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

Annotations cover the safety profile (readOnly=false, idempotent=true, destructive=false, openWorld=true), and the description adds genuinely useful behavior the annotations cannot convey: that spendCap is Meta's hard stop which halts all ad delivery once reached, that it is in whole currency units, and that null removes it. It stops short of stating reversibility of a rename or whether partial updates are allowed.

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, front-loaded with the operations, then the one piece of non-obvious semantics. No filler; every clause carries information.

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

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

For a mutation tool with no output schema, the description covers what changes and the consequence of spendCap well. The remaining gap is the ambiguous adAccountId vs accountId/profileId relationship (one required, two optional with defaults), which is left entirely to the schema.

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

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

Schema description coverage is only 40%, so the description must compensate. It adds real semantics for spendCap (currency units, null-to-remove, delivery consequence) beyond the schema's bare number/null constraint, but says nothing about adAccountId (which has only a pattern, no description) or how it differs from accountId/profileId. Partial compensation for the coverage gap.

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

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

States a specific verb+resource (rename an ad account, set/remove its spending limit) and is clearly distinguishable from siblings like ads_create_account and ads_get_account. The two supported operations are enumerated up front.

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

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

Usage is implied by naming the operations and by explaining the effect of spendCap, but there is no explicit when-to-use/when-not guidance and no routing to alternatives (e.g., ads_set_status for delivery toggling). Adequate but leaves the agent to infer context.

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 flag this as a non-read mutation in an open world; the description adds the crucial behavioral context they omit - posts go public by default, TikTok videos refuse any non-public privacy_level, YouTube keeps uploads private until the API audit (surfaced via privacyRestricted), and multipart uploads are REST-only.

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

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

Dense but front-loaded - purpose and the public-posting warning come first, then per-platform rules. Nearly every sentence carries actionable platform-specific information, though the single dense block is longer than ideal and slightly harder to scan than a segmented layout would be.

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

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

No output schema exists, yet the description tells the agent what comes back (privacyRestricted, publishId) and what to do with it (poll the matching status tool). Combined with the per-platform guidance, an agent has everything needed to invoke this correctly across all four platforms.

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 and does most of it: it maps each platform to its accepted payload shape, prefers {"url": "https://..."} over base64 for TikTok/YouTube, explains post_mode MEDIA_UPLOAD, and lists YouTube's required fields. It omits secondary fields (is_aigc, cover_timestamp, brand_* toggles, category_id, tags) and never explains accountId/profileId, so it falls short of complete compensation.

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

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

Names a concrete verb (publish) and the platforms it targets, and clearly separates itself from read-side siblings like list_posts and the *_post_status pollers. An agent can tell exactly what this tool does without opening the schema.

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

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

Gives explicit prerequisites and alternatives: call get_tiktok_creator_info before a TikTok post, poll get_tiktok_post_status / get_facebook_post_status / get_youtube_post_status for async video, and confirm content with the user first. It even states which values the agent must ask the user for rather than choose.

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 state destructiveHint=true and openWorldHint=true generically; the description adds substantial context beyond them: TikTok's limited deletion scope, YouTube's rejection of non-owned comments, the irreversibility of YouTube deletes, and the banAuthor side effect that also bans the commenter. This is exactly the kind of behavioral detail annotations cannot convey.

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

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

Front-loads the core action, then adds platform-specific rules, then the confirmation caution. Every sentence carries real information, though the run-on YouTube clause is dense enough to warrant a slightly less than perfect score.

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

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

For a destructive, credential-scoped tool with no output schema, the description covers platform divergence, side effects, irreversibility, and user-confirmation expectations. Nothing an agent needs to invoke it safely is missing.

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

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

Schema coverage is 60%, and the description compensates by explaining the non-obvious banAuthor parameter ("true" also bans that commenter). It also clarifies how platform affects behavior, though it does not spell out the platform enum values or the accountId/profileId linkage beyond what the schema provides.

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

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

Opens with a specific verb+resource ("Permanently delete a comment") and goes further by spelling out the platform-specific scope of deletion. An agent can immediately distinguish this destructive single-comment operation from siblings like update_comment, list_comments, or reply_to_comment.

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

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

Gives clear when-to-use context per platform and names an alternative action ("hide other people's comments instead" on TikTok) plus an explicit confirmation requirement. It stops short of formally mapping when to prefer update_comment or reply_to_comment over deletion, so not a full 5.

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

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

Annotations already flag destructiveHint=true, but the description goes well beyond them by specifying exactly what is destroyed (credentials and cached history), what is preserved (the provider-side account), and the downstream consequence that reconnecting requires the owner to re-authorize. That is precisely the context an agent needs before a destructive call.

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

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

Three short sentences, each carrying distinct information: the action and scope, the side-effect boundary, and the required confirmation. The most important constraint is front-loaded with zero filler.

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

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

For a destructive, no-output-schema tool, the description covers scope, what is and isn't destroyed, reversibility implications, and a user-confirmation requirement. Nothing an agent needs to invoke it safely is missing.

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

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

Schema description coverage is 100%, with accountId and profileId both documented in the schema, so the baseline is 3. The description adds no additional parameter semantics such as defaults or format expectations beyond what the schema already provides.

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

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

The description names a specific verb and resource ('Remove Adeli's credentials and cached history for one account') and scopes it to a single account, which cleanly separates it from siblings like refresh_accounts or start_connect. An agent can identify the operation without opening the schema.

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

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

It gives a procedural precondition ('Confirm with the user first') but never states when to choose this over alternatives such as refresh_accounts or start_connect, nor when disconnection is inappropriate. Usage is implied rather than explicitly routed.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered elsewhere. The description adds the useful detail that the payload includes connection status as well as metadata, but says nothing about auth requirements, what happens for a disconnected or unknown account, or error behavior. With annotations carrying the safety burden, 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?

A single front-loaded sentence with no filler or redundancy. Every word contributes: the verb, the cardinality, the resource, and the two things returned.

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 two-parameter read tool with full schema coverage and no output schema, the description conveys what is fetched and implicitly what comes back (metadata plus connection status). It is nearly complete; only edge-case behavior (missing/disconnected account) is unaddressed, which is a minor gap given the annotations.

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

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

Schema description coverage is 100%: accountId already says 'An accountId from list_accounts' and profileId documents its default binding, so the schema does the heavy lifting including the cross-tool provenance hint. The description adds no parameter detail beyond that, so the baseline 3 is correct.

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 verb ('Return') and a precise resource ('one connected account's metadata and connection status'), which cleanly separates it from the plural list_accounts. It does not, however, name or differentiate itself from near-neighbors like ads_get_account or refresh_accounts, so it falls short of a 5.

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

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

Usage is only implied: 'one connected account' signals a single-record lookup rather than a list, which is enough to distinguish it from list_accounts in practice. There is no explicit when-to-use statement, no prerequisites, and no named alternative for cases where the agent might want bulk data.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the useful polling/repeat-call semantics, but says nothing about session states, timeout, or what completion looks like.

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

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

One sentence, zero waste, with the key dependency (start_connect) front and center. Nothing to trim.

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 polling tool with no output schema and an undocumented required parameter, the description is thin: an agent cannot tell what the response contains or how to judge when polling is finished. It is minimally viable but leaves a real gap for its tool type.

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

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

Schema coverage is exactly 50%: profileId is documented in the schema, connectionSessionId is not. The description only implicitly tells the agent the session ID comes from start_connect; it adds no format or sourcing detail beyond that, so baseline 3 is right.

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 (poll) and resource (connection session) and ties it to the sibling that creates it, start_connect. An agent can distinguish this from start_connect and other read tools, though it doesn't say what the polled session represents.

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?

"Poll" plus "started by start_connect" gives clear context: call this repeatedly after start_connect until the session resolves. It stops short of saying when to stop polling or what states to expect, and names no alternative, 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 cover the read-only safety profile, and the description adds a real behavioral constraint: the read_insights permission gate and the specific time windows (28-day, recent posts) of the returned data. It does not clarify what happens when the permission is missing (error vs. partial payload), leaving one gap.

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

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

A single dense sentence that is front-loaded with the primary return value (follower count) and expands into the insight breakdown. Every clause carries information, though the parenthetical list makes it slightly heavy.

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

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

With no output schema, the description carries the burden of describing returns, and it does so reasonably well by enumerating the metric categories. The main omission is the behavior when read_insights is not granted.

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

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

Schema description coverage is 100% and both optional UUID parameters are documented in the schema itself. The description adds no syntax or default behavior beyond what the schema already provides, so baseline 3 applies.

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

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

States a specific verb (Return) and resource (Facebook Page metrics), then enumerates exactly what is returned: follower count, engagement from recent posts, and 28-day Page Insights. This clearly distinguishes it from siblings like get_instagram_insights and get_youtube_channel_insights.

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

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

The description states a gating condition ('when the connection has granted read_insights'), which is a useful usage prerequisite. However, it never says when to choose this tool over the other platform-metrics siblings, nor what to do if the scope is absent.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context with 'asynchronous', signaling that results may not be final on first call, but says nothing about what status values exist or whether repeated polling is expected.

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

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

A single tight sentence with the action and lookup key front-loaded and zero filler.

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

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

For a read-only status check with no output schema, an agent gets the essential 'what' but not the return shape (e.g., possible statuses) or the two remaining parameters. Adequate but with clear gaps given there is no output schema to lean on.

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 the description only clarifies publishId (the identifier of the publish operation). accountId (required) and profileId (optional) are left entirely unexplained, so the description does not compensate for the coverage gap.

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

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

States a specific verb (Check) and resource (asynchronous Facebook Reel/video publish) keyed by publishId, and the 'Facebook' qualifier distinguishes it from get_tiktok_post_status and get_youtube_post_status. It does not explicitly call out those siblings, but the platform scoping makes the target 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 word 'asynchronous' implies this is a polling tool used after initiating a publish, which gives implicit context. However, it never states when to call it versus an alternative, nor any precondition (e.g., that a publishId must first be obtained from a create/publish call).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds the metric categories returned, which is genuinely useful, but omits the reporting period, granularity, and any permission/account-type constraints. With no output schema, more behavioral context on the return would have been 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?

A single well-formed sentence that front-loads the resource and enumerates the returned metrics. No filler and nothing redundant with structured fields.

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 tool with full schema coverage, the description is minimally adequate but thin: with no output schema, it never specifies the reporting period, whether the response is aggregated or per-post, or what 'engagement' concretely includes. An agent could call it, but cannot predict the payload.

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

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

Schema description coverage is 100%: accountId is documented as coming from list_accounts and profileId as defaulting to the API-key-bound profile. The description adds no parameter-level meaning beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb ('Return') and resource ('an Instagram professional account's insights') and names the metric categories returned. The Instagram platform qualifier implicitly separates it from the TikTok/YouTube insight siblings, but no sibling is named or contrasted 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?

No guidance on when to use this versus get_tiktok_account_insights, get_facebook_page_metrics, or ads_get_insights. No prerequisites, no note about which account types (professional/business) qualify, and no indication of what time window the insights cover.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds meaningful behavioral context beyond that: this call returns the scope boundary that governs every other tool, which tells an agent why the result matters. It stops short of describing auth failure modes or return shape.

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

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

Two short sentences with zero waste. The 'what it returns' statement comes first and the scoping significance follows, so it is well front-loaded.

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

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

For a zero-parameter read with annotations covering safety, the definition is nearly complete; the scoping note is the key thing an agent needs. The only missing piece is what fields the returned profile contains, which is not covered by an output schema.

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

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

The tool takes zero parameters, which is the baseline-4 case: there is nothing for the description to document beyond what the empty schema already shows.

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 ('Return the profile') plus the binding key constraint. The phrase 'your API key is bound to' distinguishes it from sibling reads like get_account and from update_profile, which mutates the same resource.

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

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

Usage is implied: the description conveys this is an identity/bootstrap call ('every other tool is scoped to this profile'), which hints at calling it first. However, it never says when to use this over get_account or list_accounts, and offers no exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered; the description goes further by disclosing data retention (60 days), ingestion lag (1-2 days), the default window, and null-field behavior for personal accounts and accounts under 100 followers. These are concrete data-quality traits an agent cannot get from the annotations. It still doesn't mention rate limits or pagination.

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

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

Two tightly packed sentences: the first states purpose and payload, the second front-loads the window default, retention, and null caveats ahead of any detail. Every clause carries operational value with no filler.

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

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

With no output schema, the description appropriately enumerates the returned metric categories and the null-field limitation, and annotations cover the read-only/open-world profile. An agent has enough to call it correctly, though a note on date-range bounds interaction or result granularity would close the remaining gap.

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

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

Schema coverage is only 50% (startDate and endDate have no schema descriptions), but the description compensates by defining the date window as UTC and specifying the default fallback of the last 28 complete days. This gives meaningful semantics for the two undocumented date parameters, though it doesn't clarify the format (already in schema) or behavior when only one bound is supplied.

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

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

States a specific verb (Return) and resource (a TikTok account's daily metrics), then enumerates the exact metric families (views, likes, comments, shares, followers) and demographic breakdowns. It is implicitly distinguishable from video-level siblings like get_tiktok_video_insights because it scopes to the account, but it never names or contrasts a sibling 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 gives useful operating context (default window of 28 complete days, 60-day retention) that implies when the tool is applicable, but it never states when to choose it over get_tiktok_analytics, get_tiktok_video_insights, or get_tiktok_creator_info. Usage is left to inference from the account-level scope.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the shape of the returned data (profile + aggregate counts), but says nothing about auth requirements, rate limits, or freshness of the metrics, so it only modestly exceeds the structured data.

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

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

A single sentence, front-loaded with the verb and resource, listing the returned fields with zero filler. Nothing is wasted.

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

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

With no output schema, the description carries some burden for explaining returns and does list the aggregate fields, which is helpful. However, for a tool sitting among several TikTok analytics siblings it omits any disambiguation, leaving a real gap for correct tool 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 100%, so both accountId and profileId are already documented in the schema, including the note that accountId comes from list_accounts and profileId defaults to the key-bound profile. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb ('Return') and resource ('TikTok account's profile and aggregate statistics') and enumerates the returned metrics (followers, following, likes, video count). It is clear, but it does not distinguish itself from the nearby sibling get_tiktok_account_insights, which an agent could easily confuse it with.

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 no when-to-use guidance, no prerequisites, and never names the obvious alternative (get_tiktok_account_insights / get_tiktok_creator_info) or the condition that would select one over the other. The agent is left to infer routing from the name alone.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful framing that the returned capabilities are creator-specific current state, but discloses nothing about auth requirements, rate limits, or freshness of the data. Lower bar from annotations justifies a 3.

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

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

Two sentences, zero filler, with the returned-fields list front-loaded ahead of the usage hint. Every clause earns its place.

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

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

No output schema exists, and the description names the returned data (privacy levels, interaction settings, max video length), so return-value expectations are largely met. The remaining gap is the unexplained account/profile parameter distinction.

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

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

Schema coverage is 0% and neither accountId (required) nor profileId is explained. The description says 'the TikTok creator's' without clarifying which parameter identifies the creator or how the two IDs differ, leaving the agent to guess at invocation. With two undocumented params this needs to compensate and does not.

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

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

Specific verb (return) plus resource (TikTok creator's posting capabilities) and an explicit enumeration of what it yields: allowed privacy levels, interaction settings, maximum video length. This clearly separates it from sibling read tools like get_tiktok_account_insights or get_tiktok_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?

Gives an explicit trigger: call before create_post for TikTok, which establishes a clear workflow precondition. It does not mention alternatives or when not to use it, so it falls short of a full when/when-not/alternatives statement.

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

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

Annotations already declare readOnlyHint and openWorldHint, and the description adds genuinely useful behavior: the set of terminal statuses, the fact that SEND_TO_USER_INBOX means a draft rather than a live post, and that postIds lag behind PUBLISH_COMPLETE by minutes (an implicit polling cadence). It stops short of naming non-terminal/in-progress states, so not a 5.

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

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

Two tight sentences, front-loaded with the operation and then the return-value semantics. No filler, no restatement of the name or title.

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

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

With no output schema, the description does useful work by enumerating terminal statuses and the delayed postId. However, it omits non-terminal statuses an agent polling this tool will actually encounter, and leaves accountId/profileId unexplained, leaving gaps for a 3-parameter 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% across three parameters, so the description must carry the load. It only mentions publishId implicitly; accountId and profileId — including the required-vs-optional distinction and when profileId is needed — are never explained anywhere.

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 ('Check an asynchronous TikTok publish by its publishId') and defines the scope as async publish status, which separates it from the sibling insights/analytics tools. It never explicitly names the sibling it is not (e.g. get_tiktok_analytics or get_tiktok_account_insights), so it lands at 4 rather than 5.

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

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

Usage is implied: you call it with a publishId returned by an asynchronous publish flow, and polling is hinted at because postIds arrive minutes after PUBLISH_COMPLETE. There is no explicit when-not guidance and no mention of alternative tools for synchronous posts.

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

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

Annotations already cover the read-only safety profile (readOnlyHint=true) and external reach (openWorldHint=true), so the bar is lower. The description adds genuinely behavioral detail not in the annotations: omitting videoIds silently returns the most recent posts, and the call is scoped to at most 20 posts. It does not say what happens if more than 20 ids are passed (error vs truncation) or describe pagination.

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

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

Two sentences, no filler, and the return contents are front-loaded ahead of the parameter guidance. Every clause carries information the agent needs.

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

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

With no output schema, the description usefully compensates by enumerating the metric categories that come back and by stating the per-post scope and 20-post cap. Minor gaps remain around over-limit behavior and whether results are ordered or paginated, but nothing essential to making the call is missing.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents videoIds format and the accountId/profileId provenance. The description still adds value by explaining the omit-videoIds default and pointing to list_posts as the id source, which the schema does not state.

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 concrete verb and resource ('Return counters and watch metrics') and enumerates the exact metric families (watch time, full-watch rate, retention, impression sources, audience), which unambiguously separates it from the account-level get_tiktok_account_insights. It does not explicitly name which sibling to use instead, so it stops short of full sibling differentiation.

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

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

Gives actionable invocation context: 'videoIds is a comma-separated list of post ids from list_posts' tells the agent where ids come from, and 'omit it for the most recent posts' defines the default path when no ids are supplied. No explicit when-not-to-use or alternative-tool routing (e.g. vs get_tiktok_account_insights for account-level data) is given.

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

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

With readOnlyHint=true and openWorldHint=true already declared, the description adds real value: the data-lag behavior (two-to-three-day Analytics latency) and the authorization prerequisite (analytics scope must be granted on the connection). It does not describe failure behavior when the scope is missing or any rate-limit/throttling characteristics, so it is strong but not complete.

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 written sentences: return contents first, then default window and rationale, then the permission requirement. Every clause earns its place and the most decision-relevant information (what you get) is front-loaded.

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

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

With no output schema and four parameters, the description carries the burden well by enumerating the returned metrics and demographics, stating the default time window and its cause, and flagging the analytics-grant prerequisite. An agent has enough to decide to call it and to predict the result shape.

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

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

Schema coverage is only 50% – startDate and endDate have no schema descriptions – and the description compensates by defining them as a UTC date window with a stated default of 28 days ending three days ago. accountId and profileId semantics are covered by the schema itself. The description does not restate the YYYY-MM-DD format or the boundary inclusivity of the window, leaving minor gaps.

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 (Return) and resource (a YouTube channel's analytics), then enumerates the exact metrics returned: views, watch time, average view duration, subscribers gained/lost, likes, comments, shares, top 10 videos, and audience demographics. That scope ('channel' + daily metrics) cleanly separates it from the per-video sibling get_youtube_video_insights without needing the schema.

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

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

Gives clear operating context: the default window (28 days ending three days ago), why that default exists (Analytics lags two to three days), and the precondition that the connection must have granted analytics. It stops short of naming an alternative tool or stating when a caller should prefer video-level or other-platform insights, so it is context-rich but not exhaustively 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?

Annotations mark it readOnly/openWorld, and the description adds real behavioral value by enumerating the possible status values (processing/published/failed) and explaining that privacyStatus reflects what YouTube actually applied, i.e. it may differ from what was requested.

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

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

Two tight sentences; the identification instruction comes first and the return-value semantics second, with no filler.

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

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

With no output schema, the description covers the meaningful return fields (status, privacyStatus), so an agent knows what comes back. The only shortfall is the unexplained accountId/profileId 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% and three parameters exist, so the description must compensate. It successfully explains videoId as the publishId from create_post but says nothing about accountId or profileId, leaving a genuine 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?

States a specific verb and resource ('Check a YouTube upload by its videoId'), and clarifies scope by pointing at the create_post publishId, which separates it from sibling insight tools like get_youtube_video_insights.

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

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

Gives a clear triggering context — call it after create_post to inspect the returned publishId — but does not explicitly state when not to use it or name a competing alternative.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds a genuinely useful default ('omit it for the 20 newest') and the 50-video cap, but says nothing about rate limits, the default date window, or pagination/truncation behavior for large accounts.

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, metrics front-loaded, then the parameter behavior. No filler, no restating the title, and the most decision-relevant constraint (the 50-video cap and default set) is packed into the second sentence.

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

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

With no output schema, listing the returned metrics is essential and it does so. The remaining gap is the date window: the schema says 'give both dates or neither' but the description never states what window applies when both are omitted.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: videoIds is a comma-separated list sourced from list_posts, and omitting it selects the 20 newest videos. That default is not documented anywhere in the input 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?

Specific verb (Return) plus an explicit enumeration of the metrics returned (views, watch time, average view duration and percentage, likes, comments, shares, subscribers gained) and the resource scope (up to 50 videos over a window). This clearly separates it from the sibling get_youtube_channel_insights, which operates at channel level.

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

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

Gives concrete operating context: videoIds comes from list_posts, and omitting it returns the 20 newest videos. It stops short of naming the alternative tool (channel insights) or stating when this tool is the wrong choice.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuinely new behavior: a 'partial' status still returns loaded accounts and 'errors' lists the rest, which is non-obvious for a list call. It stops short of describing pagination, ordering, or rate limits.

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

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

Three short sentences, all front-loaded: purpose first, then call-order guidance, then response caveat. Every sentence adds information an agent needs.

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

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

With no output schema, the description usefully covers the partial-response and errors shape, and the call-order note makes it usable as an entry point. What is missing is parameter-level meaning (0% schema coverage), which is the one substantive gap for a tool that is meant to be called first.

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

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

Schema description coverage is 0% for all three parameters, so the description carries the full burden and largely fails: it never explains what the accountId parameter does on a list tool, never says profileId scopes the result, and never notes that platform filters the list. It also lists only four platforms while the enum includes 'whatsapp', creating a mismatch an agent could trip over.

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

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

States a precise verb+resource ('List the ... accounts connected to the profile') and enumerates the platforms returned, so the scope is unambiguous. It never names a sibling (e.g. get_account for a single account, or ads_list_accounts for ad accounts), so the agent must infer differentiation from scope alone.

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

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

'Call this first: every other account-level tool takes an accountId from here' gives explicit sequencing guidance and explains why the tool matters in the workflow. Nothing is left to inference about when to invoke 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 declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuinely useful behavior beyond that: replies are identified via parentId, pagination is cursor-based only on TikTok/YouTube, and YouTube review-held comments surface with isHidden true.

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

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

Four tight sentences, each carrying a distinct fact (scope, default post, reply linkage, pagination, hidden comments), with the core purpose front-loaded and no filler.

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

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

With no output schema, the description does useful work describing return semantics (parentId, isHidden) and pagination, and it covers the two required params. It is only slightly incomplete in not addressing profileId or default ordering beyond 'newest post'.

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

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

Schema coverage is only 40%, so the description must compensate, and it does for postId (omittable to get the newest post) and cursor (fed from nextCursor). However it says nothing about profileId, and platform/accountId meaning rests on the schema itself, leaving part of the gap unfilled.

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 (List) and resource (comments) scoped to one post across four named platforms, which cleanly separates it from siblings like list_posts and list_messages. An agent can identify the tool without opening the schema.

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

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

Gives real usage rules: omit postId to target the newest post, and pass nextCursor back as cursor for the next page on TikTok/YouTube. It does not name when to prefer a sibling (e.g., reply_to_comment or delete_comment for other comment operations), so it falls short of explicit alternatives.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered and the bar is lower. The description adds the useful behavioral note that results can be narrowed to keep the response small, but says nothing about ordering, pagination, volume caps, or what a DM record 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?

Two short clauses, zero filler, and the core purpose is front-loaded before the filtering hint. Nothing here would be cut without losing 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 three-parameter, zero-coverage schema with no output schema, the description leaves too much open: profileId is unexplained, the platform list conflicts with the enum, and there is no return-shape, ordering, or volume information an agent would need to use the results.

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. It mentions platform and accountId as filters (adding the 'keep the response small' rationale) but ignores profileId entirely, and gives no semantics distinguishing accountId from profileId or clarifying platform's enum values.

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

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

States a specific verb and resource ('Read Instagram and Facebook direct message history'), which lets an agent separate it from list_posts, list_comments, and send_message. However, the description names only two of the five platforms allowed by the schema enum, so the stated scope is narrower than reality and no sibling is named as an alternative.

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

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

The only guidance is 'Filter by platform or accountId to keep the response small,' which is a parameter tip rather than a when-to-use statement. There is no indication of when to prefer this over list_comments/list_posts, or any prerequisite/context for reading DM history.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description usefully adds what the payload contains per platform (TikTok adds views/shares/reach, YouTube adds views), but says nothing about the recency window ('recent' is undefined) or pagination/result caps.

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

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

Two dense sentences, front-loaded with the action and resource, and the per-platform metric caveat is compact and earns its place. Nothing is redundant.

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

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

There is no output schema and 0% schema documentation, so the description should do more. It covers the core operation and metric variance but omits the undocumented profileId parameter and any indication of result size, ordering or time range.

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. It explains the purpose of platform and accountId as filters, but leaves profileId completely unexplained, and its platform list (Instagram, Facebook, TikTok, YouTube) omits whatsapp even though the schema enum includes it.

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

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

States a specific verb and resource ('List ... posts') and enumerates the platforms covered plus the engagement payload, so an agent can tell it apart from list_comments, list_messages and the per-platform insight tools. It stops short of explicitly naming a sibling it is not, so it is clear but not maximally differentiated.

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 line 'Filter by platform or accountId to keep the response small' is an implied usage hint, but there is no when-to-use/when-not guidance and no routing to an alternative tool (e.g. per-post insight tools). Usage must be inferred from context.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so 'Safe to repeat' largely restates structured data. The description does add one genuinely behavioral fact not covered by annotations: the mutation applies to every account on the profile, not a single account. It says nothing about partial-failure handling or whether existing tokens are invalidated.

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

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

Two short sentences, zero filler, and the core action and scope are front-loaded before the repeatability note.

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

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

For a single-optional-parameter bulk mutation with full annotation coverage and no output schema, the description is adequate but thin: it omits what happens if refresh fails on some accounts and what the caller observes afterward. Annotations carry the safety profile, so the gap is moderate rather than severe.

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

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

There is only one optional parameter and schema description coverage is 100%, with the schema itself explaining that profileId defaults to the key-bound profile. The description adds no additional meaning about the parameter, which is the expected baseline when the schema does the work.

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

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

States a specific verb (Refresh) and resource (provider tokens of every account on the profile), with the operation's scope made explicit. No sibling tool performs token refresh, so an agent can distinguish it from update_account, get_account, and disconnect_account without inspection.

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

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

Usage is implied by the operation (refresh tokens when they are stale or before an expiring call), but the description offers no explicit when-to-use, prerequisites, or sequencing relative to get_account/update_account. 'Safe to repeat' hints at re-invocation tolerance but does not define a trigger 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?

Annotations only declare the write/open-world/safe profile; the description adds real behavioral context beyond them: a YouTube comment write burns 50 units of a daily quota shared across all Adeli users, and the resulting comment is public. The quota and public-exposure warnings are exactly the kind of consequence an agent cannot infer from structured fields.

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

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

Front-loaded with the parentId/postId branching, then platform caveats, quota cost and the confirmation requirement. Every sentence carries distinct information, though the nested parentheticals make the second sentence dense.

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 public write with no output schema, the description covers the branching logic, platform scope, quota cost and the user-confirmation safeguard. Remaining gaps (error behavior, whether a comment can be edited afterward) are minor given the sibling set provides update_comment and delete_comment.

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

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

Schema coverage is only 33% (accountId and profileId documented), so the description must carry the load for postId, parentId, message and platform. It does explain the conditional semantics of parentId vs postId and the platform-dependent requirement, adding meaning the schema alone does not convey, though message constraints and platform enum implications are left to the schema.

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

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

States a specific verb (reply/comment) plus the two distinct resources it targets (a comment via parentId, a post via postId), and scopes the post-only path to Facebook, TikTok and YouTube. This distinguishes it cleanly from siblings like create_post, update_comment and delete_comment.

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

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

Gives concrete routing rules: use parentId to reply, postId-only to comment on your own posts, and both for TikTok/YouTube replies. It also states the pre-call requirement to confirm text with the user. It stops short of naming alternative tools for overlapping cases (e.g., update_comment).

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful non-annotation context: WhatsApp sends must use an approved template, and the payload is exactly the JSON body of POST /api/v1/messages. It stops short of describing delivery failures, rate limits, or idempotency.

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

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

Three tightly packed sentences, front-loaded with the capability, then the payload contract, then the safety instruction. No filler or restatement of the title.

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

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

No output schema exists, so return values are undocumented, but the description covers the platform variants, payload contract, recipient sourcing and the confirmation requirement, which is most of what an agent needs. Absence of error/response behavior is the remaining gap.

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

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

Schema coverage is 0%, so the description carries the burden, and it does add meaning: the single `message` param is the exact POST /api/v1/messages body, and `recipient` is a platform-scoped sender id (an E.164 phone number on WhatsApp). This clarifies field semantics the schema only encodes structurally via oneOf/patterns, though it does not explain accountId vs profileId.

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 (send) plus resource (direct message) and enumerates the exact platform variants: Instagram/Facebook text DMs and approved WhatsApp templates from the profile's own number. That scope distinguishes it cleanly from siblings like create_post, reply_to_comment and list_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?

Gives concrete operating context: recipient comes from list_messages, and it instructs the agent to confirm the text with the user before sending. It does not, however, state when to prefer this over reply_to_comment or what to do if the platform/account combination is unsupported.

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

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

Annotations only cover the safety profile (readOnlyHint=false, openWorldHint=true, destructiveHint=false); the description adds genuine behavioral context beyond them – the two-step external auth flow, the returned authUrl requiring a browser action by the owner, and the three terminal states to poll for. It stops short of stating auth requirements, expiry timing, 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?

Front-loaded with the action and resources, then the authMethod nuance, then the return/poll flow. Every sentence carries information; the Instagram branch is dense but necessary. Slightly long due to the parenthetical clause.

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

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

No output schema exists, and the description compensates by describing the return artifact (authUrl) and the subsequent polling loop, which is exactly what an agent needs for this multi-step flow. It falls short on the two undocumented platform enum values and redirectUrl, but the core lifecycle is covered.

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 only 25% schema description coverage, the description carries the load and does explain authMethod (instagram_login default vs facebook_login via the linked Facebook Page), which the schema does not. However it omits redirectUrl entirely and lists only four platforms while the enum contains six (whatsapp and google_business_profile are unmentioned), leaving real gaps.

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

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

Names a specific verb (start connecting) and the exact resource (an Instagram, Facebook, TikTok or YouTube account), and routes the agent to the follow-up tool get_connect_session, so it is distinguishable from siblings like disconnect_account or get_account. An agent knows what the call initiates without opening the schema.

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

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

Gives clear context: call this to begin an OAuth connection, then hand the returned authUrl to the account owner and poll get_connect_session until connected/failed/expired. It explains the Instagram-specific authMethod decision but offers no explicit 'when not to use' or prerequisite/scope 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 idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: YouTube hiding is a soft hold visible only to the channel, and like/unlike is TikTok-only. It still doesn't say what happens on Instagram/Facebook or how errors surface, so not a 5.

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

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

Two tight sentences with the core action front-loaded and platform caveats following. No filler, every clause carries information.

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

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

For a 7-param mutation tool with no output schema and moderate schema coverage, the description covers the highest-risk unknowns (platform-specific postId requirement, YouTube review semantics, TikTok-only like). It omits return/error behavior and non-TikTok like behavior, but the essentials for correct invocation are present.

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

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

Schema coverage is 43%, so the description must compensate. It correctly explains that postId is required for TikTok hides and that liked is TikTok-only, but leaves hidden vs liked interaction, the platform enum effects on other platforms, and profileId's default unexplained (the schema covers profileId and the two id params).

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 specific verbs (hide/unhide, like/unlike) and the resource (comment), with platform scoping that separates it from siblings like delete_comment and reply_to_comment. An agent can tell what state change this performs without opening the schema.

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

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

It supplies platform-specific conditions (TikTok needs postId to hide; like is TikTok-only), which is real usage guidance. However, it never names or excludes the obvious alternatives (delete_comment, reply_to_comment), so the agent must infer when this tool is preferred over them.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false. The description adds valuable behavioral context by clarifying that this is a full replacement of mutable fields ('as REST PUT does'), which helps an agent understand that omitted fields may be reset. It does not discuss 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?

Two short sentences with no waste, front-loading the core action and then adding a clarifying analogy. Every sentence earns its place.

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

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

For a simple update tool with annotations and no output schema, the description covers the main action and replacement semantics. However, given only 25% schema description coverage, it leaves parameter details thin and does not explain the effect of omitting optional fields.

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

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

Schema description coverage is only 25% (only profileId is described). The description names three parameters (name, externalId, metadata) but provides no additional semantics about their formats, constraints, or how profileId interacts. It does not compensate for the low coverage beyond listing the fields.

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 ('Replace') and resource ('the profile's name, externalId and metadata'), making the tool's effect clear. It does not differentiate from siblings like get_profile or update_account, but the core 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?

Usage is implied ('Replace the profile's...') but there is no explicit guidance on when to use this versus alternatives such as get_profile or whether it is for partial updates. The PUT analogy hints at full replacement but doesn't state when that is appropriate.

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