AdsAgent — Meta Ads MCP

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

Annotations already declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, so the safety profile is fully carried by structured data. The description only adds the 'login identity only' scoping boundary. With an output schema present, there is little else for the description to disclose; 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?

Two short fragments, front-loaded with the scope statement before the routing hint. No wasted words. It is arguably clipped to the edge of intelligibility, but every token 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 zero-parameter read tool with a full output schema and complete annotations, the description covers the only thing the schema and annotations cannot convey: what this profile represents (login identity) and where the alternative lives. Adequate, if terse.

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, so there is nothing for the description to compensate for. Baseline 4 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 the exact scope of the resource: the login identity profile, and contrastively marks what it does not cover. An agent can distinguish it from setup_get_status and account_media_* siblings. No explicit verb, but the name plus scope makes the operation unambiguous.

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

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

The description gives a clear routing rule: use this for login identity, use setup_get_status for channel setup. It names the alternative and the condition that selects it, though it never states why an agent would need the login identity in the first place.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds no behavioral context beyond the read semantics — nothing about what happens with an unknown or malformed media_ref, whether the reference resolves to a URL or metadata, or any scope limitation. Adequate but thin against the lower annotation-backed bar.

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 clause with a semicolon-joined routing hint; zero filler, and the disambiguation arrives after the action is established.

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

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

An output schema exists, so return-value explanation is not required, and the single-parameter surface is simple. The one remaining gap is provenance — nothing indicates that media_ref values come from account_media_list — which would have made it fully self-contained.

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, and it only restates the parameter concept ('account media reference') which is tautological with media_ref. The only real semantics — the ^media_e1\.[A-Za-z0-9_-]+$ pattern and where such a reference is obtained — come from the raw JSON schema, not the description.

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

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

States a specific verb ('Read') plus a bounded resource ('one account media reference') and immediately contrasts it with the batch sibling. An agent can distinguish it from account_media_get_batch and account_media_list without opening any schema.

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

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

Explicitly names the alternative (account_media_get_batch) and the condition that selects it ('for multiple selections'), which is the core routing decision for this tool. It leaves account_media_list unmentioned, so the list-vs-get case is still left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety is covered. The description adds interaction-sequencing behavior (list the index first) and a batching rationale (avoid serial probes) that annotations do not convey. It does not describe cursor/pagination behavior, which limits it to a 4.

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: action, cap, sequencing, and the anti-pattern are all packed in and the most important constraint leads.

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

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

An output schema exists, so return values need not be explained, and the batch semantics plus sequencing are covered. The unexplained optional cursor (pagination) is the one meaningful omission for a batch fetch with a cursor field.

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 parameter meaning. 'selected ... after listing the index' helpfully implies media_refs are references obtained from account_media_list, and the 50-item cap aligns with maxItems. However, ad_account_id and especially the cursor parameter are not explained anywhere, 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?

States a specific verb ('Fetch'), resource ('account media previews'), scope ('up to 50 ... in a batch'), and sequencing ('after listing the index; avoid serial item probes'). This implicitly but clearly separates it from the single-item sibling account_media_get and the index tool account_media_list.

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?

Tells the agent when to reach for it ('after listing the index') and what to avoid ('serial item probes'), which is actionable context. It stops short of naming account_media_get / account_media_list as explicit alternatives, but the intended usage pattern is clear.

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

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

Annotations already declare this is a read-only, non-destructive, closed-world operation, so the safety profile is covered. The description adds the setup policy check but omits pagination behavior and what the index entries contain, which would matter for a list operation.

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

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

The description is short and front-loads the listing action and follow-up workflow. The final policy-check clause is terse but still useful and does not add unnecessary bulk.

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

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

The presence of an output schema and strong annotations reduces the burden, but with 0% schema description coverage the description should clarify the required account/media parameters and cursor pagination. It gives the broad workflow but not enough parameter guidance for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate for all four parameters. It only implies the 50-entry limit and says nothing about ad_account_id, media_type, or cursor usage.

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 ... account media index entries'. It also points to the batch follow-up, though it does not distinguish from the single-item account_media_get sibling.

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

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

Gives a clear workflow: select candidates here, then use account_media_get_batch. It also names a prerequisite to check via setup_get_status policy, but does not explain when to use account_media_get instead.

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

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

Annotations already establish readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds essentially no behavioral detail beyond a restatement of the purpose – nothing about what provenance data is returned, whether credentials/tokens are exposed, or what the 'operation' parameter changes.

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

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

It is a single front-loaded phrase with no waste, which is good. But the brevity crosses into under-specification rather than economy, since the phrase is the entire description.

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

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

An output schema exists, so return values need not be explained. Still, with an undocumented required parameter, an unexplained 'operation' switch, and no differentiation from the many account_* siblings, the definition is not complete enough for confident invocation.

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

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

Schema description coverage is 0%, so the description is responsible for explaining both parameters. It mentions neither ad_account_id nor the 'operation' parameter (default 'pull'), leaving the agent with no idea what operations are available or what the required account identifier should be.

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?

"Find account owner and token provenance" names a verb and an outcome, so the intent is discernible. But it never defines what 'owner' or 'token provenance' means in this system and does not distinguish itself from nearby siblings such as account_get_profile, accounts_get_account_detail, or assets_lookup_business_links.

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?

There is no statement of when to use this tool, when not to, or which sibling to prefer for ownership or account metadata questions. The agent must infer the routing decision entirely from the name.

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

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

Annotations already cover read-only/non-destructive/closed-world, and the description meaningfully adds freshness semantics ('app bindings are cached') and an explicit scope limitation ('no BM links'), which an agent needs to know before relying on the result. It still leaves unanswered what 'live' means relative to the cache and whether the account must be pre-bound.

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 the caching/BM caveats trailing correctly. The 'BM topology: assets_lookup_business_links' fragment is terse to the point of being cryptic but does not waste much space.

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

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

An output schema exists, so the description needn't enumerate returned fields, and annotations cover the safety profile. What remains missing — how to obtain a valid ad_account_id and what 'detail' encompasses — is modest for a one-parameter read tool.

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

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

Schema coverage is 0% for the single ad_account_id parameter, so the description must carry the load; it does so partially by implying the account must be one 'authorized in your workspace', which constrains valid values. It gives no format, source, or discovery guidance (e.g. from assets_list_ad_accounts).

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 live Meta details for one ad account'), scoped to accounts authorized in the workspace. It is reasonably distinguishable from assets_list_ad_accounts/assets_refresh_ad_account, though the second sentence's 'app bindings are cached, no BM links' is a caveat rather than purpose and adds a slightly cryptic flavor.

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 'one ad account authorized in your workspace' and the pointer to assets_lookup_business_links for BM topology gives a partial routing hint. However there is no explicit statement of when to use this instead of assets_refresh_ad_account, assets_list_ad_accounts, or account_get_profile, nor any exclusion.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds one piece of genuine context – '(snapshot read)', signaling that results are a point-in-time snapshot rather than live data – but says nothing about staleness, pagination, or scope of eligibility.

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 short sentence with the scope and snapshot caveat front-loaded; nothing is padded. Slightly terse for the amount of information an agent might want, but no waste.

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

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

An output schema exists, so return values need not be described, and annotations carry the safety profile. For a one-parameter read tool this is largely complete; only the semantics of 'eligible' (which permissions/criteria) are left implicit.

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 the single required ad_account_id, so the description must compensate. 'On one ad account' confirms the parameter identifies a single account, but no format, ID-prefix, or example is given.

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

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

States a specific verb+resource (list pages) with a clear scope (eligible for ad creation, on one ad account) plus a snapshot-read qualifier. It is distinguishable from assets_list_pages by the eligibility/ad-creation framing, though it never explicitly names a sibling.

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

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

The phrase 'eligible for ad creation' implies when the tool applies, but there is no explicit when-to-use, when-not-to-use, or named alternative (e.g. assets_list_pages vs. this narrower ad-account-scoped listing). Guidance is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered and the bar is lower. The description adds nothing beyond that — not that results are paginated, not that it requires an ad account plus page pair, and nothing about ordering or result 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?

Three words is short, but this is under-specification rather than concision — there is no front-loaded statement of scope or behavior to be efficient about.

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

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

An output schema exists, so return values need not be described, but the tool takes two mandatory identifiers and two pagination parameters with zero documentation anywhere. For a two-identifier retrieval tool the description leaves an agent unable to call it correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden for all four parameters, yet it explains none of them. Both required identifiers (ad_account_id, page_id) and the pagination controls (limit, cursor) are completely undocumented.

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?

"List IG IDs" restates the tool name almost verbatim and only names the resource in abbreviated form (IG IDs). It does not say the listing is scoped to an ad account and page, nor how it differs from assets_list_instagram_accounts or accounts_list_eligible_pages.

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?

There is no indication of when to use this tool, no preconditions, and no reference to any of the closely named sibling tools that also deal with Instagram accounts and pages. The agent has to guess 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 readOnly/non-destructive/closed-world, and the description adds real context beyond them: it reads stored rows rather than live Meta, 'refresh' re-reads those rows, and no work is queued or snapshot saved. That clarifies the staleness model, which is the main risk with a list 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?

Front-loaded with the purpose, then constraints, then the cross-reference; no filler sentences. It is slightly telegraphic ('Filter then paginate'), which costs a little readability but not correctness.

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

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

With an output schema present and annotations covering safety, the description supplies the missing behavioral framing (stored data, no sync) that an agent needs. Gaps are limited to per-parameter detail, mainly fb_user_label and search matching.

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 must carry parameter meaning; it only explains 'refresh' and gestures at filter/paginate. It says nothing about limit bounds, cursor semantics, what 'search' matches, or what fb_user_label filters on.

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 ('Read linked Meta ad accounts and their Facebook connection labels') and pins the source ('from stored workspace routing'), which is a real distinction. It does not distinguish itself from the closest siblings assets_list_ad_accounts or connections_list, so an agent still has to infer which list is authoritative.

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 excludes sync/queue/snapshot behavior and routes BM-link lookups to assets_lookup_business_links, which is useful. However, the more likely confusion (this vs assets_list_ad_accounts / assets_list_businesses / connections_list) is never addressed, so usage is only implied for the main cases.

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

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

Goes well beyond the annotations by disclosing the two-phase approval model (draft saved here, applied only via the confirm tool), the returned artifacts (approval_ref, plan_digest), and the key safety fact that 'This call does not change delivery.' That is exactly the context an agent needs before invoking a non-destructive-but-write-adjacent prepare step.

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 short clauses, front-loaded with purpose, then return values, then the safety caveat, then the sibling preference. Every sentence carries information an agent would otherwise have to guess.

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

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

Return values are partly explained (though an output schema exists) and the approval workflow is fully covered. The remaining hole is bidding semantics — units/currency of bid_amount and any validation constraints — which matters for correct invocation of a bid change.

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 implies what the parameters are. It never explains what bid_amount is denominated in (account currency, minor units, cap vs. target bid), nor what form adset_id / ad_account_id take. With all three parameters undocumented elsewhere, the description should compensate and largely 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?

States a specific verb + resource + scope: 'Prepare one ad set bid-amount change' and pairs it with the concrete action 'read current Meta settings ... and save an approval draft.' The bid-amount qualifier implicitly separates it from siblings adsets_prepare_budget_change and adsets_prepare_status_change, and the description names both the confirm tool and entities_prepare_update.

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 sequencing rule ('apply only after approval with operations_confirm_adset_bid') and points to an alternative ('Prefer entities_prepare_update for new work'). The alternative condition 'for new work' is vague and no explicit when-not-to-use is given, so it falls short of full routing guidance.

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

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

Adds real context beyond the annotations: the call is a draft/approval step that "does not change delivery", it reads current Meta settings from the "authorized account", and it returns approval_ref and plan_digest that the confirm tool consumes. Missing are draft lifetime/expiry, whether repeat calls create duplicate drafts, and any rate-limit or permission nuance - though the annotation set already covers the safety profile (destructiveHint=false).

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 clauses, front-loaded with the purpose, then the return/apply contract, then the sibling routing. No filler, though the trailing "Prefer entities_prepare_update for new work" is terse to the point of being cryptic given the size of the sibling set.

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

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

The output schema already covers return values and annotations carry the safety profile, so the description only needs the workflow and input contract - which it largely delivers. The gap is on the input side: for a budget-mutating prepare step, nothing explains budget units, validation bounds, or what happens to an unapproved draft.

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 parameter burden, and it does not. It implies the three inputs (ad set, ad account, daily budget) but never states ID formats, currency or minor-unit semantics for daily_budget, or any minimum-budget constraint - the single most likely source of a bad call.

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: "Prepare one ad set daily-budget change", and immediately bounds the scope ("one ad set", daily budget only). It also distinguishes itself from the apply step (operations_confirm_adset_budget) and the general-purpose sibling (entities_prepare_update), so an agent can place it in the workflow 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 clear sequencing ("apply only after approval with operations_confirm_adset_budget") and an explicit alternative ("Prefer entities_prepare_update for new work"). The condition for the alternative, "new work", is left slightly ambiguous - it could mean new budget changes vs. new entities - so it stops short of a clean when/when-not rule.

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

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

Goes well beyond the annotations: it discloses that the call writes an approval draft but 'does not change delivery', and names the returned handles (approval_ref, plan_digest) required for the confirm step. With readOnlyHint=false and destructiveHint=false already declared, this adds the crucial nuance that the write is a draft, not a live 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?

Four short sentences with the purpose first, then the return contract, then the safety caveat, then the alternative. Every sentence carries distinct information; only the return-value mention is mildly redundant given an output schema exists.

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

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

The prepare→confirm workflow, non-mutating nature, and outputs are all covered, and an output schema means return shapes need no explanation. The remaining gap is that three required parameters, including the enum-typed status, are never explained in prose.

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 supplies no meaning for adset_id, ad_account_id, or target_configured_status beyond the enum in the schema. 'Read current Meta settings in your authorized account' hints at account scoping but does not clarify whether ad_account_id must match the adset's owning account or what the status values mean operationally.

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 ('Prepare one ad set status change') plus the exact side effect ('save an approval draft'), which cleanly distinguishes it from ads_prepare_status_change and campaigns_prepare_status_change by scope. An agent knows what entity it acts on without opening the schema.

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

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

Explicitly names the follow-up tool ('apply only after approval with operations_confirm_adset_status') and routes new work elsewhere ('Prefer entities_prepare_update'). It doesn't state when to use this versus the sibling prepare tools for ads/campaigns, but the ad-set scoping plus the named next step covers the main decision.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The word 'stored' adds modest value by signalling the copy is read from previously stored data rather than fetched live, but nothing is said about behavior when an ad id is missing or how partial results are handled.

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 with the verb and scope front-loaded and no filler. Minor loss for the noun-phrase fragment style and the bare 'type' field which is slightly ambiguous.

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

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

An output schema exists so return values need not be explained, and annotations cover safety. For a one-parameter read tool this is close to sufficient, but the batch-size limit is mentioned without saying what happens on invalid ids, and the description does not situate the tool in the copy-edit workflow despite many sibling prepare/confirm tools.

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

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

Schema coverage is 0% and the single parameter ad_ids has no description, but the parameter name is self-explanatory. The description does add one real constraint the schema lacks: the 1-50 count bound, which the schema does not encode via minItems/maxItems.

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 ('Read stored copy') plus resource ('1-50 ads') and an enumerated list of the fields returned (texts, links, button, Page, preview, type), so the agent knows exactly what it gets back. It does not distinguish itself by name from the nearby ads_update_copy_prepare/confirm family, but the read-vs-write intent is clear enough from 'Read'.

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 statement of when to use this versus alternatives such as ads_update_copy_prepare (the obvious pairing for editing copy) or render_ad_previews. The 1-50 bound implies batching but not when to batch instead of single calls.

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

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

Adds real context beyond the annotations: readOnlyHint=false could read as a live mutation, but the description states 'This call does not change delivery' and that it saves a draft, plus notes the read of current Meta settings in the authorized account. It stops short of saying what happens to a superseded draft or whether drafts expire.

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 short sentences, front-loaded with the action and scope, followed by the return values, the safety constraint, and the alternative routing. 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?

The prepare/approve/confirm workflow and key outputs (approval_ref, plan_digest) are covered, and an output schema exists so return detail is not required. The gap is parameter-level meaning for a tool with zero schema coverage, and no note on permissions or draft lifecycle.

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 never mentions ad_id, ad_account_id, or target_configured_status; the ACTIVE/PAUSED enum is only implied by 'status change'. With three undocumented required parameters, the description fails to compensate for the schema 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 ('Prepare one ad status change') plus the exact scope ('one'), and explicitly separates it from the apply step by naming operations_confirm_ad_status. An agent can distinguish it from the confirm sibling without opening either schema.

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

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

It gives the sequencing rule clearly ('apply only after approval with operations_confirm_ad_status') and names an alternative, entities_prepare_update. The alternative's qualifier 'for new work' is vague, and no explicit when-not-to-use condition is given for existing status changes on ads.

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 disclose that this is destructive, non-read-only, idempotent, and closed-world. The description adds the scope ('one Meta ad') and state transition ('current to approved value'), but it does not explain confirmation-token handling, expiry, or the practical effect on the existing media beyond replacement.

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

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

The description is a single front-loaded sentence with no wasted text. The action and state transition are stated 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?

The presence of an output schema and rich annotations reduces what the description must cover, and the core mutation is stated. Still, for a destructive confirm operation with 0% parameter-description coverage, the description leaves gaps around confirm_token semantics and the old/new value parameters.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It only implicitly maps 'current to approved value' to old_value/new_value and 'just confirmed' to confirm_token, without naming parameters or explaining the required confirm_token, entity_name, or value formats.

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

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

The description states a specific action: run a confirmed change that sets the reviewed media field of one Meta ad from the current value to the approved value. It distinguishes the confirm step from preparation/denial through 'the user just confirmed,' though it does not explicitly name the sibling prepare/deny tools.

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

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

The phrase 'the change the user just confirmed' implies this should be used only after user confirmation, which is useful context. However, it does not explicitly state when not to use it or point to ads_replace_creative_prepare / ads_replace_creative_deny as 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 destructiveHint=true, readOnlyHint=false, and openWorldHint=false, so the safety profile is largely covered. The description adds the useful detail that this acts on a prepared swap, but it does not explain what denying does to the pending operation or whether it is final.

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 phrase with no filler. Every word contributes to identifying the operation.

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

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

The tool is low-complexity and has an output schema, but the required confirm_token is undocumented and the prepare/deny workflow is only implied. For a destructive confirm/deny operation, the description should at least state where the token comes from and what denial does.

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 sole required parameter, confirm_token, is never mentioned in the description. The phrase 'prepared' weakly implies a token comes from a prepare step, but the parameter's meaning and source are not clarified.

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: 'Deny' a 'prepared in-place creative swap.' This clearly identifies the operation, though it does not explicitly differentiate from siblings like ads_replace_creative_confirm or ads_replace_creative_prepare.

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 by saying the swap is 'prepared,' so the agent can infer this is the rejection path in a prepare/confirm workflow. However, it never states when to deny versus confirm or what prerequisite must be satisfied.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, but the description does not explain what 'prepare' actually does: whether it merely stages a pending operation, whether any change is applied before confirmation, or what happens if the agent never calls confirm/deny. For a mutation-adjacent tool, the key behavioral fact (nothing changes until confirmed) is left unstated.

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

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

The single sentence is front-loaded and free of filler, so it is efficient. However, its brevity here is under-specification rather than discipline — the space saved is space the agent needed.

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

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

An output schema exists, which relieves the description of explaining return values, but the tool still carries 8 undocumented parameters and an unstated prepare→confirm/deny lifecycle. Given that complexity, one sentence is not enough for an agent to invoke it correctly.

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

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

Schema description coverage is 0% across 8 parameters, and the description adds no parameter meaning at all. Worse, four overlapping names — creative_name, creative_names, new_creative_name, replacement_creative_name — are mutually ambiguous and the definition gives no rule for which to supply or whether they are alternatives.

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 phrase 'Prepare in-place library-creative swap on an existing ad' gives a specific verb (prepare) and resource (creative swap on an ad), which is enough to separate it from confirm/deny siblings by name pattern alone. It stops short of explicitly naming ads_replace_creative_confirm as its counterpart, so the workflow role must be inferred.

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 never states when to call this versus ads_replace_creative_confirm / ads_replace_creative_deny, nor that it is the first step of a staged approval flow. The only hint is the shared naming prefix in the sibling list, which is inference rather than 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?

The annotations already disclose that this is a destructive, non-read-only, idempotent operation, so the description does not need to restate those traits. It adds some context by framing the call as applying a previously reviewed user-confirmed change to one ad, but it does not explain the confirmation mechanism or the consequences of executing the 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?

The definition is a single front-loaded sentence with no filler. The phrasing is slightly awkward ('Run the change the user just confirmed: set...') but remains compact and 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?

Although an output schema and annotations reduce the burden, the input schema has zero description coverage and the description leaves the required confirm_token and entity_name semantics unexplained. For a destructive confirmation tool, that is a meaningful completeness gap.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It implies that old_value/current and new_value/approved correspond to the field transition, and entity_name relates to the one Meta ad, but it never explains the required confirm_token or clarifies the entity scope.

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

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

The description states a specific action: applying a user-confirmed change to one Meta ad by setting an identity field from current to approved value. It is distinguishable from the adjacent prepare/deny siblings through the phrase 'the user just confirmed,' though 'reviewed identity field' is slightly vague compared with the tool name's explicit 'page' replacement.

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 clearly indicates the tool should be used after the user has confirmed the change, which gives an agent a usable gating condition. It does not explicitly name the matching prepare or deny alternatives, but the usage context is still understandable.

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 this is a non-read-only, destructive operation. The description adds useful context that it denies a previously prepared page swap, but it does not explain side effects, reversibility, or what happens to the pending operation.

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

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

The description is a single front-loaded phrase with no wasted text. It is perhaps too terse, but it is structurally efficient.

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

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

Even with annotations and an output schema, the definition leaves key operational context missing for a destructive denial action: the confirm_token contract, relationship to the prepare/confirm flow, and consequences of denying are not 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?

There is one required parameter, confirm_token, with 0% schema description coverage. The description does not explain where the token comes from, whether it is single-use, or how it relates to the prepared swap.

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: deny a prepared in-place page swap. It is clearly distinct from prepare/confirm variants by the verb 'deny', though it does not explicitly name those siblings as alternatives.

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 implies the operation follows a preparation step via 'prepared', but gives no explicit guidance on when to deny versus confirm or abandon, nor any prerequisites beyond that weak implication.

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=false. The description adds meaningful context beyond those: it may upload media to Meta, and the swap is not applied until a separate confirmation step, which is important for an agent deciding whether to call it.

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

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

The description is three short clauses and is front-loaded with the core action. Every clause carries useful information, though the telegraphic style leaves some terms ('page swap') underspecified.

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

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

Given 8 parameters, 0% schema description coverage, and a prepare-style mutation that may upload media, the description is too thin. The output schema and annotations carry some burden, but the agent still lacks basic guidance on which page-related parameters to supply and what the preparation produces.

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

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

The schema has 8 parameters with 0% description coverage, and the description mentions none of them. It does not explain the differences between ad_id, ad_account_id, account_id, page_id, page_ids, new_page_id, facebook_page_id, or ad_name, so the agent receives no semantic guidance for a highly ambiguous parameter set.

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 ('Prepare') and resource ('page swap'), and indicates it is a preparatory step rather than the final application. It distinguishes itself from the confirm sibling by saying 'Confirm separately to apply', though it never explicitly names the ad object being changed.

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?

There is a clear workflow hint: prepare now, confirm separately to apply. However, it does not name the alternative tool (ads_replace_page_confirm), state when to use this versus ads_replace_creative_prepare, or describe prerequisites such as required page permissions.

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

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

The annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds that it applies approved values to one ad's reviewed text fields, but does not add operational context such as token requirements, failure behavior, or what happens on repeated calls beyond the idempotency annotation.

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

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

The single sentence is front-loaded with the core action and avoids filler. It is appropriately sized for the information it conveys, even though more information would be needed for completeness.

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?

A mutation tool with four undocumented parameters and a required confirm token needs more than a one-line description, even though annotations cover safety and an output schema exists. The description omits how the token is used, what old_value/new_value mean, and the prerequisite confirm flow, leaving important invocation context unstated.

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

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

Schema description coverage is 0%, with four parameters including the required confirm_token. The description vaguely implies old/new values and an ad entity, but it never explains confirm_token, entity_name, old_value, or new_value, so it does not compensate for the lack of schema documentation.

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

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

The description states a specific action — running a previously confirmed change — and scopes it to reviewed text fields on one Meta ad, moving them from current to approved values. It is clear what the tool does, but it does not explicitly name the sibling prepare/deny tools it pairs 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 phrase 'the change the user just confirmed' implies the tool should be called after a prior confirmation step, which is useful context. However, it does not explicitly state prerequisites such as calling ads_update_copy_prepare first, nor when to use ads_update_copy_deny instead.

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

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

Annotations already declare destructiveHint=true, so the safety profile is known. The description adds valuable context: despite being destructive, it only discards prepared edits and does not change the actual ad, clarifying the scope of destruction.

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

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

The description is a single, front-loaded sentence with zero waste. It efficiently conveys the core action and a key constraint.

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

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

The tool has a required parameter with no description and an output schema, but the description omits parameter guidance and usage context relative to siblings. It is too sparse for a destructive deny operation with a required confirm token.

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 does not mention the required confirm_token parameter at all. With no explanation of what the token is or where to obtain it, the description fails to compensate for the schema gap.

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

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

The description states a specific verb ('Discard') and resource ('prepared copy edits'), and clarifies the resource scope ('without changing the ad'). It does not explicitly name or distinguish from the confirm sibling (ads_update_copy_confirm), but the deny action is clear from the tool name and description.

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 usage by stating the tool discards prepared copy edits, but it offers no explicit guidance on when to choose this over ads_update_copy_confirm or ads_update_copy_prepare. No alternatives or exclusions are mentioned.

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

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

Annotations already declare the tool is non-readonly, non-destructive, and closed-world. The description adds useful scope information: edits are limited to body/title/description and media/Page are preserved. But it omits the critical behavioral detail that this is a prepare step that requires a separate confirm action before changes take effect, and it doesn't say whether the edit is staged or immediately applied.

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

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

The description is a single front-loaded sentence with no wasted words. It is appropriately compact, though the terse phrasing makes the staged prepare/confirm workflow slightly opaque.

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

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

An output schema exists, so return values need not be explained. Annotations cover the safety profile. But for a prepare-step tool in a larger confirm/deny workflow, the description should explicitly connect to ads_update_copy_confirm/deny and explain that no changes occur until confirmation. It also leaves the required ad_account_id undocumented.

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

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

Schema description coverage is 0%, so the description must compensate. It names four of the five parameters (body, title, description, ad_id) and clarifies they apply to a single Ad, which is helpful. However, it completely omits ad_account_id, a required parameter, and provides no format or constraint details for any field.

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

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

The description states a specific action (prepare edits) and the exact fields affected (body/title/description) on a specific resource (Ad ID). It also implicitly distinguishes itself from the media- and Page-replacement prepare siblings by saying media and Page are preserved. It falls short of 5 because 'prepare' alone doesn't fully explain the staged nature of the operation.

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

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

The phrase 'preserving media and Page' implies this is the right tool when only copy fields change, and conversely not the right tool when creative or Page must change. However, it never explicitly names the alternative tools (ads_replace_creative_prepare, ads_replace_page_prepare) or states that confirm/deny steps follow. Usage is implied rather than stated.

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

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

Annotations declare readOnly=false, destructive=false. The description adds meaningful context beyond that: 'Prepare' signals the mutation is staged, not applied, and 'confirm/deny via operations' tells the agent the actual change requires a follow-up call. Missing auth/permission notes but the deferred-mutation semantics are well conveyed.

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 compact sentence that front-loads the action and scope. No wasted words, though it is terse to the point of omitting parameter detail.

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

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

An output schema exists so return values needn't be described. But with 0% schema coverage and no parameter explanation, plus minimal workflow guidance, the definition is only minimally complete for a prepare-mutation 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% for 3 required params (ad_account_id, ad_id, destination_url). The description does not explain any parameter semantics, leaving the burden unmet. Parameter names are fairly self-evident, but the description adds nothing over the bare schema.

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

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

States a specific verb+resource: 'Prepare a destination URL change on the same Ad ID'. This clearly distinguishes it from ads_update_copy_prepare and from the confirm/deny siblings by noting confirmation happens via operations.

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?

'confirm/deny via operations' implies a staged workflow where this prepare step precedes confirmation, which gives useful context. However, it does not explicitly state when to choose this over alternatives or prerequisites (e.g., that the ad must exist / correct account).

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

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

The annotations say readOnlyHint=false with destructiveHint=false, which is confusing for a 'List' tool; the description resolves it by disclosing that cache miss/authorized refresh can queue private work — a real write side effect beyond what annotations encode. It stops short of saying whether queued work is async or how long it takes.

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?

Very short and the purpose is front-loaded, but the semicolon fragments and the bare trailing tool name read as notes rather than sentences, costing clarity for the space saved.

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

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

An output schema exists, so return values need not be explained, and the mutating side effect is covered. With five undocumented parameters and no stated prerequisites for the private-work path, it is only minimally 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 coverage is 0%, so the description carries the burden. It maps loosely onto four of five params — filtering (search), pagination (limit/cursor), refresh — but never names them, and fb_user_label ('routing flags'?) stays ambiguous.

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 Meta ad accounts') plus scope ('this workspace can use') and an output trait ('with routing flags'). It is distinguishable from assets_list_businesses / assets_list_pages, though it never explicitly contrasts itself with those siblings.

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

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

'filter then paginate' gives an operating hint and 'Cache miss/authorized refresh may queue private work' tells the agent a refresh has cost. The dangling 'assets_lookup_business_links' implies a fallback but never states the condition that selects it, so usage is only implied.

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

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

The description adds real context beyond the annotations: a cache miss or authorized refresh 'may queue private work', which explains why readOnlyHint=false on a list tool. That said, 'private work' is undefined — the agent gets no sense of what is queued, whether it is pollable, or when the cache is considered populated.

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?

Very short and front-loaded with the purpose, which is good. But the remaining content is telegraphic fragment-stacking ('Cache miss/authorized refresh may queue private work') and a bare sibling name, so brevity costs clarity rather than earning it.

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

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

An output schema exists, so return shape needn't be described. Still, for a five-parameter list tool with zero schema coverage, the description leaves too much unexplained: no meaning for refresh or fb_user_label, no indication of result ordering or how 'visible to this workspace' is scoped.

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 five parameters, so the description carries the full burden and largely fails it. 'filter then paginate' loosely maps to search/limit/cursor, but refresh and fb_user_label — the two parameters whose behavior matters most — are never explained in either the schema or the description.

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

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

States a specific verb and resource ('List Meta Business Managers') plus a scope qualifier ('visible to this workspace'), which separates it from the sibling assets_list_pages and assets_list_ad_accounts by resource type. It does not explicitly name those siblings, so differentiation is implicit rather than stated.

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

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

'filter then paginate' implies an intended call sequence (search before limit/cursor), which is useful operational guidance. However, 'assets_lookup_business_links' is appended without any condition explaining when to prefer it, leaving the routing decision to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context by saying the data is cached and comes from Auto Pull Assets, implying possible staleness, but it does not describe freshness, pagination, or search behavior.

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

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

It is a single front-loaded sentence with no wasted words. The terseness is efficient, though it leaves out useful routing and parameter context that would justify the tool's four inputs.

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

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

An output schema exists, so return values need not be explained in the description. However, for a filtered listing tool with four undocumented parameters and no usage guidance, the description is too incomplete to ensure correct invocation; the cached-source note is the only substantive addition.

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 four parameters, and the description does not mention limit, cursor, search, or ad_account_id at all. The agent is left to infer all parameter meanings from names alone, so the description adds no semantic value beyond the raw schema.

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

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

The description states a specific verb (List) and resource (cached Instagram IDs and names) plus its source (Auto Pull Assets). It is clear, but it does not explicitly distinguish this tool from close siblings such as accounts_list_instagram_accounts or other assets_list_* tools.

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

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

There is no explicit guidance on when to use this tool, when not to use it, prerequisites, or which sibling handles live versus cached Instagram account listing. The agent must infer routing from the name and one terse sentence.

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

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

Adds real context beyond annotations: 'Cache miss/authorized refresh may queue private work' explains why readOnlyHint is false on a list operation and warns about asynchronous side effects. It stops short of saying what 'private work' produces or how long it takes.

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?

Very compact and front-loaded: purpose first, then side-effect caveat, then workflow hint. The final bare tool name without a connecting phrase costs a bit of readability but no sentence 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?

An output schema exists so return values need no explanation, and the side-effect caveat covers the main behavioral risk. However, with five undocumented parameters and an unexplained 'authorized refresh' concept, an agent still lacks enough to call it confidently in non-default cases.

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

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

Schema coverage is 0%, so the description must compensate, but it only gestures at 'filter' (search) and 'paginate' (limit/cursor) without naming or explaining them. The refresh flag and fb_user_label are left entirely unexplained, as are the limit bounds.

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

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

States a specific verb and resource: 'List Facebook Pages this workspace can advertise with, with health.' The scope ('this workspace', 'can advertise with') distinguishes it from generic page listings like fb_users_list, though the sibling differentiation is implicit rather than spelled out.

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?

'filter then paginate' implies a call pattern, but the trailing 'assets_lookup_business_links' is a dangling reference with no verb or condition explaining when to prefer it. No explicit when-not or prerequisites are 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?

Annotations already establish a safe, read-only, closed-world operation, so the bar is lower. The description adds genuinely useful context beyond them: results are cached/snapshot edges that may be incomplete, a negative result is not proof of absence, and the call is OAuth-safe. The cryptic 'OAuth-safe' phrasing is the only weak spot.

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?

Very short and front-loaded: purpose first, then the selection rule, then the caveats. Telegraphic fragments like 'OAuth-safe' are slightly under-explained, but 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?

An output schema exists, so return-value detail is unnecessary here. For a four-parameter lookup, the description covers the selection rule and the key data-quality caveat; only per-parameter value formats are 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 0%, so the schema itself says nothing about the four parameters; the description carries the load. It names all four and adds the crucial exclusivity constraint (exactly one, never asset ID plus FB user), but it does not explain the expected value format or semantics of each identifier.

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 cached BM links') and clarifies that the data comes from a cached snapshot. An agent can tell what it returns, though it does not name a sibling (e.g. assets_list_businesses) as the alternative for non-link data.

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 selection rule: choose exactly one of business_id, ad_account_id, page_id, or FB-user identity, and never combine an asset ID with an FB user. It also tells the agent how to interpret a miss ('no match does not prove no relationship'). It stops short of naming sibling tools or stating when this lookup 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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, covering the safety profile. The description adds only 'cached', hinting the choices come from a pre-fetched store (possibly stale), but says nothing about what happens on ambiguous matches or whether selection prompts further interaction.

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 compact sentence with the selection target front-loaded and no wasted words. Brevity is appropriate, though it edges toward under-specification rather than efficient density.

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

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

For a 3-parameter tool with 0% schema description coverage, the description is too thin: it omits the meaning of two parameters and any selection-flow context. The output schema and annotations cover returns and safety, but the input side is left largely unexplained.

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, yet it never mentions 'search' or 'ad_account_id' at all. The 'kind' values are visible only via the enum; two optional parameters remain completely undocumented in both description and 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 ('Choose') and resource ('ad account, Facebook Page or Instagram account'), with the scope qualifier 'cached' and 'one' implying a single-selection picker. This implicitly distinguishes it from the many assets_list_* siblings, but never names them, so the differentiation is inferred rather than stated.

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

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

There is no explicit guidance on when to use this picker versus assets_list_pages, assets_list_ad_accounts, or creatives_pick. It also never explains when to supply 'search' or 'ad_account_id', leaving the agent to guess at the selection workflow.

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

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

The annotations already declare that this is not read-only, not destructive, and not open-world, so the safety profile is mostly covered structurally. The description adds useful scope by saying it refreshes one account and its connection Page cache, but it does not explain side effects, permissions, or whether the refresh is immediate or queued.

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

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

The description is a single compact sentence with no filler and the action and scope are front-loaded. It is concise, though its brevity contributes to gaps covered under other dimensions.

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

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

An output schema exists and annotations cover the safety profile, so return values and mutation risk need not be explained. However, with 0% schema description coverage and a close sibling like assets_refresh_all, the description is missing enough selection guidance and parameter semantics to be 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 0%, so the description must carry the burden of parameter meaning. It vaguely refers to 'one account' and 'Page cache', which loosely maps to ad_account_id and page_id, but it does not explain formats, required versus optional behavior, or what page_id controls.

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, 'Refresh', and a clear resource scope: one account plus its connection Page cache. It implicitly distinguishes itself from the bulk sibling assets_refresh_all through the word 'one', but it does not explicitly name or route against that 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 description gives no explicit guidance on when to use this tool versus assets_refresh_all, assets_list_ad_accounts, or other refresh tools. It implies a single-account refresh scope but does not state prerequisites, exclusions, or selection criteria.

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 this is a non-read-only, non-destructive, closed-world operation, so the safety profile is covered. The description adds the useful nuance that the work is queued (asynchronous) rather than synchronous, but says nothing about scope of the refresh, cost, whether existing snapshots are replaced, or how completion is observed.

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 five-word sentence with the key verb and object front-loaded and no filler. Its brevity is a virtue here, since the tool takes no arguments.

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

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

An output schema exists so return values need not be described, and annotations cover the mutation profile. However, for a fire-and-forget bulk refresh, the definition never says what 'all' covers, whether it applies per connection or globally, or how it interacts with assets_refresh_ad_account — meaningful gaps an agent would want filled.

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

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

The input schema has zero parameters, which is the baseline-4 case; there is nothing about parameters the description could or should explain. The schema's emptiness is consistent with the 'refresh all' framing.

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 ('Queue') plus a specific resource ('asset snapshot refresh'), so the agent knows it enqueues rather than performs the refresh. It does not explicitly distinguish itself from the sibling assets_refresh_ad_account, leaving the 'all vs. one account' scope to be inferred from the name.

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

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

There is no statement of when to use this tool versus assets_refresh_ad_account or assets_lookup_business_links, nor any precondition such as needing a connection first. The only hint of applicability is the word 'all' embedded in the tool name.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the scoping fact that only the caller's assets are searched, which is useful, but says nothing about result limits, ranking, 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?

One front-loaded sentence with no filler; the purpose and scope are conveyed in a single clause with zero wasted words.

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

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

An output schema exists, so return values need no explanation, and annotations cover safety. However, the description leaves open what happens when the optional 'query' is omitted and how the mention search is scoped to results, which matters for a tool with zero required parameters.

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

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

The single 'query' parameter has 0% schema description coverage and the description never mentions it, so an agent gets no help on what the query string matches or how maxLength=100 interacts with it. With one undocumented parameter, the description does not compensate for the schema 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 ('Search') and enumerates the resource domains ('ad accounts, products and campaigns') plus the scope ('composer @-mentions'). An agent can distinguish it from siblings like assets_list_ad_accounts or assets_pick, though it never names an alternative 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 phrase 'composer @-mentions' implies the context of use (autocomplete while composing), but there is no explicit when-to-use, no exclusions, and no pointer to any alternative search tool. Usage is inferred rather than stated.

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

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

Annotations already flag this as a destructive, non-read-only mutation, so the description should disclose what is actually affected. It does not say whether omitted flags are left untouched or reset, whether existing permissions are revoked, or that changes affect routing for the whole ad account — key risks for a destructive permission change.

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 clause with no filler, listing exactly the fields touched. Its brevity is efficient, though the terseness borders on a fragment that assumes the reader knows the domain.

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 four undocumented parameters and a required ad_account_id, the description omits the most consequential facts: partial-update semantics and the blast radius of a permission change. The existing output schema covers return values, but that does not offset the missing behavioral and parameter context.

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 parameter meaning. It names three of four flags but adds no semantics beyond the names — no explanation of what allow_create/allow_pull/allow_decision control, no mention of ad_account_id, and no partial-versus-full update behavior.

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

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

States a specific verb and resource (update account permission routing flags) and names the three flags affected. The resource distinction from the sibling fb_users_update_permissions is implicit in the tool name but not reinforced in the text, 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?

No guidance on when to use this versus alternatives (e.g., fb_users_update_permissions) and no prerequisites such as required permissions or account ownership. The agent must infer the entire usage 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 readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds a billing-context note (free during beta), but says nothing about rate limits, scope of data returned, or whether omitted meter/period/channel default to something — a meaningful gap for a billing read.

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 and no redundancy. It is efficient, though its brevity borders on under-specification for a tool with three undocumented parameters.

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

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

An output schema exists so return values needn't be described, but the definition is missing what an agent needs: parameter meaning, whether all params are optional (0 required), and what defaults apply. For a 3-param billing tool with zero schema coverage, the description does too little.

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 three parameters (meter, period, channel), so the description carries the full explanatory burden and fails: it says nothing about valid meter values, period format (date range? month?), or what channel filters. 'Plan and measured usage' only loosely gestures at meter/period semantics.

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

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

States a specific verb (Read) and resource (plan and measured usage), which is clear enough for an agent to know the tool returns billing/usage data. No sibling in the list is a billing tool, so differentiation isn't an issue, but the description doesn't clarify scope (what 'plan' data vs 'measured' usage means).

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?

There is no guidance on when to call this tool, what prerequisites exist, or what alternatives to prefer. The parenthetical '(free during the public beta)' is a cost note, not usage guidance, and does not help an agent decide when this tool is appropriate.

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 annotations present (readOnly=false, destructive=false), the description still adds real context: it creates a persisted approval draft, returns approval_ref and plan_digest, and explicitly does not alter delivery until a separate confirm call. This two-phase, no-side-effect-on-delivery behavior is exactly the kind of trait annotations alone cannot convey.

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

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

Three short sentences, front-loaded with the action and effect, followed by the follow-up dependency and the alternative. 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?

Annotations cover the safety profile, an output schema covers the return refs, and the description covers the prepare/confirm workflow and sibling alternative. Only parameter units are missing, which is minor for a three-field 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% and none of the three required parameters (campaign_id, ad_account_id, daily_budget) are explained. Nothing states the currency/unit of daily_budget, the format of the IDs, or that ad_account_id must match the authorized account beyond a passing mention of 'your authorized account'.

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

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

States a specific verb+resource and scope: 'Prepare one campaign daily-budget change', reading current Meta settings and saving an approval draft. The phrase 'one campaign' implicitly separates it from the plural sibling campaigns_prepare_budget_changes, and it names the downstream operations_confirm_campaign_budget, so an agent can place it in the workflow 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?

Explicit sequencing: prepare, then apply only after approval with operations_confirm_campaign_budget, and 'This call does not change delivery' clarifies when it is safe. It also points to entities_prepare_update as an alternative for 'new work', though that alternative condition is vague compared to the rest of the guidance.

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

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

Goes well beyond the annotations: despite readOnlyHint=false it clarifies 'This call does not change delivery', and it explains the draft/approval flow plus the returned approval_ref and plan_digest. That distinction — a non-readonly write that is nonetheless non-delivery-affecting — is exactly the context an agent needs and cannot get from annotations.

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

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

Four short clauses, front-loaded with the verb+resource and scope, then the return values and the approval gate. The telegraphic style ('Prefer entities_prepare_update for new work') is slightly compressed but no sentence 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?

For a draft-creating mutation, the description covers what is read, what is persisted, what is returned, what is NOT changed, and how the change is later applied. With an output schema present, return-value detail needn't be repeated, so nothing essential is missing.

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

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

Schema coverage is reported at 0% for the top-level parameter, and the description never explains the `items` array shape (campaign_id / ad_account_id / daily_budget), relying on nested schema text instead. The only added semantics are the 1-10 batch bound, which already exists as minItems/maxItems in the schema.

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

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

States a specific verb and resource ('Prepare 1-10 campaign daily-budget changes') plus the concrete mechanics (read current Meta budgets, save one approval draft). The batch scope (1-10) and draft-only nature distinguish it clearly from campaigns_prepare_budget_change (singular) and from the confirm sibling.

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

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

Names the follow-up tool explicitly ('apply only after approval with operations_confirm_campaign_budgets') and offers an exclusion ('Prefer entities_prepare_update for new work'). The phrase 'new work' is a bit vague, but the sequencing guidance around approval is unambiguous.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the description's job is lighter. It still adds real context the annotations lack: an approval draft is written, approval_ref and plan_digest are returned, delivery is unchanged, and a separate confirm tool must be called. It does not describe draft lifecycle details such as expiry or whether re-preparing overwrites a pending draft.

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 compact sentences, front-loaded with the action and the return contract, then the confirmation requirement and the alternative. Nothing is repeated from the annotations or schema, and every clause carries operational weight.

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

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

The tool has an output schema, so return values need not be spelled out in depth, yet the description still names the key outputs and the approval gating. For a three-parameter prepare tool this is nearly complete; the only material gap is that the parameters themselves are undocumented in prose.

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 gives no parameter-level guidance. It implies target_configured_status through 'campaign status change', but campaign_id and ad_account_id are not explained, and the ACTIVE/PAUSED enum meaning is left entirely to the schema. With zero coverage the description should 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?

States a specific verb and resource ('Prepare one campaign status change') and immediately distinguishes the scope from siblings by naming operations_confirm_campaign_status as the apply step and entities_prepare_update as the alternative for new work. An agent can tell this is the draft/approval stage of a two-phase campaign status mutation.

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

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

Explicitly says when to use it ('Prepare one campaign status change... save an approval draft'), what must follow ('apply only after approval with operations_confirm_campaign_status'), and what to use instead for new work ('Prefer entities_prepare_update'). It also rules out a common misreading with 'This call does not change delivery.'

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 state readOnlyHint=false and destructiveHint=false, but the description adds the critical behavioral fact that this only prepares a draft and launch_confirm executes after approval. It leaves out side effects for append mode, partial failures, and collision policies, so it is strong but not exhaustive.

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

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

The description is only three sentences and is front-loaded with the main workflow. It is slightly awkward with the run-on 'approval Use' phrasing, but otherwise every sentence carries relevant 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 tool with this much nested branching complexity, the description covers only the broad prepare/approve flow and one alternative tool. It omits important operational areas such as activation, execution/budget settings, naming collision behavior, and partial-result policies, leaving the agent under-guided despite the existing output schema and 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 reported as 0%, and the request object contains many nested fields such as groups, execution, targeting, activation, destination, and naming policies. The description names only ad_account_id, template_name, creative_source, append_mode, target IDs, and link_id, so it adds some routing semantics but does not compensate for the large undocumented schema surface.

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

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

The description uses a specific verb ('Prepare') and resource ('new ads' / existing campaign/ad set), and distinguishes the tool from copy_ad_quick_copy and launch_confirm. It does not mention the campaigns_quick_create_revise sibling, so it falls just short of fully unambiguous 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?

It explicitly says to use this for preparing new ads or appending to an existing campaign/ad set, names copy_ad_quick_copy as the alternative for live-ad copies, and explains that launch_confirm executes after approval. It gives clear context but does not cover all sibling paths such as revise or deny.

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

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

The annotations already mark this as a destructive, non-read-only mutation, so the description does not need to repeat that safety profile. It adds the useful constraint 'within its original expiry,' but it does not explain what revision invalidates, how the expected plan digest is used, or what happens if the approval has expired.

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

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

The description is a single front-loaded sentence with no filler. It is perhaps too terse for a destructive tool with a complex nested patch, but the sentence itself is efficiently structured.

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

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

For a tool with three required parameters, a nested patch object, 0% schema description coverage, and destructive behavior, this description is materially incomplete. It says what is revised and that an expiry applies, but omits parameter semantics, revision consequences, and how it relates to the surrounding prepare/confirm workflow.

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 does not explain any of the three required parameters. It gives no meaning for approval_ref, expected_plan_digest, or the nested patch structure, so it fails to compensate for the schema's lack of parameter descriptions.

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

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

The description names a specific verb and resource: 'Revise a prepared create approval.' This distinguishes it from pure preparation or confirmation tools, though it does not explicitly name the sibling alternatives it differs from.

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

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

It implies this tool is used on an already-prepared create approval before it expires, which gives some usage context. However, it does not state when to choose this over campaigns_quick_create, confirmation tools, or deny/abandon paths.

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

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

The annotations already state readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds only limited workflow context ("before prepare") and does not explain what reconciliation entails, such as validation behavior or handling of partial scope.

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

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

The description is a single short sentence with no wasted words and is front-loaded with the main action. It is overly terse for the tool's complexity, but it is structurally efficient.

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

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

Although an output schema exists and annotations cover safety, the tool involves a complex nested request and a workflow-dependent "before prepare" step. The description omits parameter semantics and does not provide enough context for an agent to invoke it confidently in the campaign-planning flow.

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

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

The tool has a nested request object with fields like ad_account_id, target_campaign_id, requested_items, currency, scope_policy, and requested_budget_minor, but schema description coverage is 0%. The description does not clarify any of these fields, including the strict/partial enum, so it fails to compensate for the schema gap.

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

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

The description names a verb ("Reconcile") and a resource ("fixed existing-Ad campaign plans"), so the general domain is identifiable. However, "fixed existing-Ad" and "before prepare" are internal workflow terms, and the description does not clarify what reconciliation means or how it differs from sibling prepare tools.

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

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

The phrase "before prepare" implies a workflow ordering, which gives some usage context. But it does not identify the specific prepare tool, describe when reconciliation is required versus skipped, or mention 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 establish that this is a non-read-only, non-destructive operation. The description adds little beyond that, omitting what gets prepared, whether a confirmation step follows, what side effects occur, and what prerequisites or permissions are needed.

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

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

The description is short and front-loads the main action before adding the link_id note. It is efficient, though the missing punctuation and cryptic final clause slightly reduce clarity.

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

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

For a mutating prepare tool with two parameters and an existing output schema, the description is too sparse. It leaves one parameter entirely unexplained and does not clarify what the preparation produces or how it relates to the confirm campaign recreation sibling.

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 parameter meaning. It only indirectly implies task_ref via 'prior create task' and never explains the failed_items_only boolean; the mention of 'original link_id' refers to a field not present in the schema, adding ambiguity.

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

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

The description states a specific action, preparing a recreation from a prior create task, which distinguishes it from ordinary campaign creation. It does not explicitly name the campaign entity or differentiate it from sibling tools like campaigns_quick_create_revise, but the core operation is clear.

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 implies the tool is used when recreating from an existing create task and adds a conditional instruction to use the workflow's original link_id when exposed. However, it gives no explicit when-not-to-use guidance or alternatives among the many campaign and operation 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 cover readOnly/openWorld/destructive, so the description only needs to add context beyond safety. It does: the accepted handle prefixes, the outcome set (status/channel vs not_found_or_expired), and the anti-polling instruction. The return-value detail is somewhat redundant given an output schema exists, which keeps this from a 5.

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

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

Front-loaded with the core verb and resource, then parameter formats, then the sibling redirect. Dense but every clause carries information; the accepted-format list is packed into one compact phrase rather than a list.

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

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

With annotations, an output schema, and one required parameter, the description supplies the missing pieces: handle formats, result semantics, polling guidance, and the sibling alternative. Complete enough to invoke correctly; only the upstream link to connections_create_intent is left implicit.

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% for the single required parameter, so the description carries the burden — and it does, enumerating the three acceptable intent_id formats (ci_*, Meta connect_id, fbconn_live_*). It stops short of format syntax or validation rules, so it compensates well but not exhaustively.

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 one existing authorization handle") plus the point in the flow ("after the user finishes"). It also distinguishes itself from the closely related setup_check_channel_connect by routing setup connect_ids there, so an agent can separate it from siblings without reading 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?

Names an explicit alternative ("For setup connect_id use setup_check_channel_connect") and a behavioral caveat ("do not start automatic polling"), which is real routing guidance. The trigger condition is only loosely implied as "after the user finishes" — it never says the handle comes from connections_create_intent, so the when-to-use framing is clear but not fully closed.

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

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

Annotations already establish that this is a non-readonly, open-world, non-destructive operation. The description adds useful behavioral context beyond annotations: the link is single-use and intended for human authorization, and the result is a connect_url.

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

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

The definition is two sentences, front-loads the core action and scope, and includes the sibling alternative without unnecessary padding. Every sentence contributes directly to correct selection or invocation.

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

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

Given the output schema and annotations, the description covers the essential action, channel values, return value, and a key alternative. It could be slightly more complete by mentioning how the resulting intent is checked or by clarifying mode behavior, but no critical invocation information 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 0%, so the description must carry parameter meaning. It does meaningfully document the accepted channel values (meta, google_ads, tiktok) and names mode=add_connection, though it does not explain mode semantics beyond that value.

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: creating a single-use browser authorization link. It scopes the tool to concrete channel values and names the returned connect_url, while also distinguishing it from setup_begin_channel_connect by workflow.

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

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

It explicitly points to setup_begin_channel_connect when an agent needs that tool's connect_id/check workflow, which gives clear alternative guidance. It does not fully address other related siblings such as connections_check_intent, so it stops short of exhaustive when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds the meaningful nuance that this yields a link plus user-facing instructions — implying a manual, out-of-band revocation rather than an in-product mutation — which is genuinely useful context an agent cannot read off annotations. It stops short of saying whether the returned link expires, is one-time, or requires an authenticated session.

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 short phrase, front-loaded with the two things the tool returns (link, steps). It is not wasteful, but the missing verb and clipping make it read as a note rather than a definition.

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 parameters, an output schema, and annotations covering safety, the description only needs to establish purpose and routing — and routing is the piece it lacks. An agent cannot tell from this text alone when revocation guidance is the right call versus the setup_* Facebook connect tools that handle the inverse flow.

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, so the baseline is 4. There is nothing for the description to disambiguate, and it correctly implies no input is needed to retrieve the guide.

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 the resource (a Facebook link) and the deliverable (steps for the user to remove AdsAgent's access), which reads as a guidance/lookup tool rather than an action. However, the phrasing is a sentence fragment with no verb, and it never states whether the tool performs the disconnect or merely returns instructions — an agent could plausibly expect either. It is distinguishable from connections_list/connections_create_intent only by inference.

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?

There is no statement of when to call this versus setup_begin_facebook_connect, setup_check_facebook_connect, connections_list, or connections_check_intent, all of which sit in the same connection domain. No prerequisites, no explicit exclusions, no named 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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds one genuine behavioral fact beyond that: results are "redacted", meaning sensitive connection data is masked — useful so the agent doesn't expect raw credentials. Pagination behavior and scope remain undisclosed.

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

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

It is a single front-loaded phrase with zero waste, which is structurally sound. But at four words it is under-specified rather than concise — there is no second sentence doing the work a listing tool needs.

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

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

An output schema and annotations exist and carry some burden, but with a filter parameter of unknown domain (`channel`), opaque cursor pagination, and an undefined notion of "connection", an agent cannot call this confidently. The description leaves the core semantics to guesswork.

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?

All three parameters (limit, cursor, channel) have 0% schema description coverage and the description explains none of them. In particular, valid `channel` values and the cursor's pagination semantics are undocumented anywhere, and the description does nothing to compensate.

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?

"List redacted platform connections" gives a verb (List) and a resource (platform connections), so the basic operation is understandable. However, "connections" is never defined (linked ad accounts, pages, channels?) and nothing distinguishes this from siblings like connections_check_intent or setup_check_channel_connect, which may also surface connection state.

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?

There is no statement of when to call this versus alternatives, no prerequisites, and no mention of the related connection tools (check_intent, create_intent, disconnect_guide). The agent must infer usage purely from the name.

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

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

Annotations already declare that this is not read-only, not destructive, and closed-world. The description adds only that the data source is stored Console metrics and the format is CSV, but says nothing about the confirm_export gate, whether an export job is created, permissions, limits, or side effects.

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

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

The description is a single, front-loaded sentence with no wasted wording. It is efficient, though its brevity is part of why important operational details are absent.

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?

This is a complex export tool with 9 input parameters and a nested scope object, and the description explains none of the input semantics or export behavior. An output schema exists, so return values need not be described, but the input-side context is still substantially incomplete.

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

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

Schema description coverage is 0% across 9 parameters, including a nested discriminated scope, several enums, and a confirm_export flag. The description does not explain any parameter, so it completely fails to compensate for the missing schema documentation.

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 (Export), resource (stored Console metrics), and output format (CSV). It is clear what the tool does, but it does not differentiate itself from the closely named sibling insights_export_csv.

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?

There is no guidance on when to use this tool versus alternatives such as insights_export_csv or console_query_overview. It also omits prerequisites, such as whether an export must be confirmed or what scope/date filters are appropriate.

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, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds only the word 'stored', which hints at reading persisted/snapshot state rather than live data, but says nothing about pagination via result_cursor, the 100-item cap, or what a stored evidence record represents.

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 five-word sentence that is front-loaded and wastes nothing, but its brevity comes from under-specification rather than efficiency — the whole definition is shorter than it needs to be for a four-parameter tool.

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

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

An output schema exists and annotations cover the safety profile, but for a tool with four parameters at 0% schema coverage and a non-obvious 'evidence' concept, the description leaves the agent unable to construct a correct call or know what to expect.

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% — none of the four parameters (entity_type, entity_ids, ad_account_id, result_cursor) has a description, and the description text mentions none of them. With no compensation at all for an undocumented schema, the agent gets no guidance on the act_ prefix handling, the numeric ID pattern, or cursor semantics.

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

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

The description gives a verb ('Read') and a resource ('stored entity configuration evidence'), so it is not a bare tautology, but 'evidence' is undefined jargon — an agent cannot tell what a configuration evidence record actually is or how it differs from console_query_overview or console_prepare_change.

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?

There is no indication of when this tool should be used, when a sibling such as console_query_overview should be preferred, or whether it requires a prior change/prepare step. The agent must infer the workflow entirely from the name.

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