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

Beyond the annotations (which only say non-read-only, non-idempotent, open-world), the description discloses that ad groups on automatic bidding are skipped, that auto-created bids are read first, that bids are clamped to min_bid/max_bid, and that the result carries old and new values. It also documents the gating rule requiring confirm='APPLY' above the PINTEREST_ADS_BULK_THRESHOLD count or any increase above PINTEREST_ADS_MAX_INCREASE_PCT, which is exactly the kind of safety context annotations cannot convey.

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

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

Four short paragraphs, each front-loaded with its topic: mode selection, clamping/skip behavior, then the confirmation gate. Nearly every sentence earns its place; the only slack is the vague trailing phrase 'with progress' in the opening line.

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

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

For a 7-parameter bulk mutation with an output schema present, the description covers the risk surface well: mode selection, boundaries, skipped entities, confirmation gating, and a dry-run-first workflow. The one real hole is ad_account_id, which is undocumented and potentially confusing given that ids alone are required.

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

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

Schema coverage is 0%, so the description must carry the meaning, and it does for change_pct (with a -10 = -10% example), set_bid (account-currency and a 0.85 example), min_bid/max_bid (clamping bounds in currency units), and confirm (literal 'APPLY' token). 'ids' is self-evident, but ad_account_id is left entirely unexplained in both schema and description.

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

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

The description opens with a specific verb and resource ('Change many ad group bids at once'), plus a scope qualifier ('many ... at once'), so an agent immediately knows this is a bulk bid mutation. It is inherently distinguishable from the sibling pinterest_ads_adjust_budgets by resource, but it never explicitly contrasts the two, which keeps it short of a 5.

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

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

It states the two mutually exclusive operating modes ('pass change_pct ... or set_bid') and prescribes a workflow ('Run in dry-run first and show the user the table'), which is strong when-to-use guidance. It stops short of naming alternatives such as update_ad_groups for single-entity edits or adjust_budgets for budget changes.

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

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

Annotations already declare the write/non-idempotent/open-world profile; the description adds real value beyond them by naming the confirm='APPLY' gate tied to PINTEREST_ADS_BULK_THRESHOLD, PINTEREST_ADS_MAX_INCREASE_PCT, and PINTEREST_ADS_MAX_BUDGET, plus the Pinterest rejection of sub-1.00 USD daily increases. This is exactly the guardrail context an agent needs before a bulk mutation. It doesn't describe partial-failure behavior, which keeps it from a 5.

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

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

The purpose is front-loaded in one clause, followed by grouped parameter and guardrail notes with no filler. The parenthetical mapping and threshold sentence are dense but each earns its place. Structure is slightly ragged, with mixed inline parentheticals rather than clean separation of modes versus preconditions.

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 unnecessary, and the description covers mode selection, parameters, and confirmation thresholds for a 7-parameter bulk mutation. The gaps are the undocumented 'ids' input (how many, what happens on invalid IDs) and whether a bulk run is all-or-nothing or partially applied.

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

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

With 0% schema description coverage, the description carries the full burden and largely succeeds: it defines entity values, budget modes, the meaning and example of change_pct (15 = +15%) and set_budget (40 = account currency), and the confirm token. However, 'ids' and 'ad_account_id' are never explained, leaving two of seven parameters undocumented anywhere.

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

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

States a specific verb and resource with scope: 'Change many campaign or ad group budgets at once'. The entity mapping (campaigns -> daily_spend_cap/lifetime_spend_cap, ad_groups -> budget_in_micro_currency) makes it clearly distinguishable from siblings like pinterest_ads_update_campaigns or pinterest_ads_set_statuses.

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

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

Gives explicit usage conditions: pick 'campaigns' or 'ad_groups' via entity, then either pass change_pct for a relative change or set_budget for an absolute value in account currency. It also states prerequisites (confirm='APPLY' above env thresholds) and a Pinterest-side constraint. It doesn't explicitly say when to use this versus the single-object update tools, but the bulk framing makes that inference easy.

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

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

Beyond the destructiveHint/idempotentHint annotations, it discloses the consequences that actually drive a decision: archived groups stop serving and Pinterest cannot un-archive them. The required confirm='ARCHIVE' gate is a concrete behavioral requirement the annotations do not 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?

Two tight sentences with the action and irreversibility front-loaded before the alternative. No redundant restatement of the title, though the confirm clause is slightly compressed into the consequence sentence.

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

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

Output schema exists so return values need not be described, and annotations cover the safety profile; the description supplies irreversibility, the confirm gate, and the pause alternative. The remaining gap is scope-related: whether ad_account_id is required context and how partial failures across multiple ids behave.

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 well for 'confirm' by specifying the exact literal 'ARCHIVE', but says nothing about 'ad_account_id' or the id-array format, leaving one of three parameters undocumented everywhere.

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 ('Archive ad groups by ID') that an agent can immediately distinguish from siblings like pinterest_ads_archive_campaigns, pinterest_ads_archive_ads, and pinterest_ads_update_ad_groups.

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

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

Explicitly routes the agent: use this to permanently archive, but use pinterest_ads_set_statuses with PAUSED for a temporary stop. It also states the precondition that the user must agree before calling, leaving nothing to inference.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, so the safety profile is partly covered structurally. The description still adds genuinely new behavioral facts: archived ads stop serving and the action is irreversible on Pinterest's side ('can't un-archive'), plus a confirmation-token gate. It stops short of describing partial-batch failures or what happens to dependent entities, which keeps it below 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?

Three tight sentences: the action, the consequence plus required confirmation, then the alternative. The irreversible nature and the confirm requirement are front-loaded ahead of the redirect to set_statuses, so a skimming agent cannot miss them.

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 this covers the critical ground: preconditions, irreversibility, and the safer alternative, and an output schema exists so return values need no explanation. The only meaningful gap is scope handling for 'ad_account_id' when archiving ads across accounts, which an agent would have to guess.

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, and it does explain the non-obvious 'confirm' parameter — the literal value 'ARCHIVE' is required. However, 'ids' is only implied by 'by ID' (no format, batch-size, or single-vs-multiple guidance) and 'ad_account_id' is never mentioned at all, leaving two of three parameters without added meaning.

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

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

The description opens with a specific verb and resource combination, 'Archive ads by ID', which tells an agent exactly what entity is affected and that the operation is batch/keyed. It does not need to distinguish itself from archive_campaigns or archive_ad_groups since the resource noun 'ads' does that work implicitly.

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

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

It gives an explicit when-not and the alternative: for a temporary stop, use pinterest_ads_set_statuses with PAUSED instead. It also states the precondition for calling it at all — the user must agree and confirm='ARCHIVE' must be supplied — leaving nothing to inference.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds context the annotations cannot: archived campaigns stop serving and cannot be un-archived by Pinterest. It also discloses the confirmation gate, which is essential behavioral knowledge for a destructive write.

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

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

Three short sentences, zero filler: operation, irreversibility plus confirmation requirement, then the alternative. The irreversible-consequence warning is front-loaded where it matters most.

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 return values need no explanation since an output schema exists, and the destructive semantics are covered thoroughly. The only gap is that ad_account_id, an optional but meaningful scoping parameter for a destructive operation, is never mentioned.

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 explains the confirm parameter's required literal value well, but leaves ad_account_id and the format of ids undocumented; the ids array is inferable from 'by ID' but account scoping is not addressed at all.

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

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

The description states a specific verb and resource ('Archive campaigns by ID') and immediately distinguishes the irreversible archive from the reversible alternative, pinterest_ads_set_statuses with PAUSED. An agent can select this tool over its siblings 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?

It names the alternative tool and the condition that selects it ('to stop them temporarily, use ... PAUSED instead'), plus a precondition: the user must agree and confirm='ARCHIVE' must be passed. When-to-use and when-not-to-use are both explicit.

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

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

Annotations already flag destructiveHint=true, idempotentHint=true and openWorldHint=true. However, the description goes beyond them by disclosing irreversibility ('can't be restored'), that keywords stop applying, the 1000-ID cap, and the required literal confirm='ARCHIVE', which the schema's bare string default does not 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 lines with no filler; the sibling pointer, the destructive nature, the confirm requirement and the batch limit are all front-loaded.

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

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

Return values need not be described because an output schema exists, and the destructive-call essentials are covered. The only meaningful omission is any explanation of ad_account_id, which is undocumented in both structured and natural-language form.

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 the burden. It explains the ids parameter (keyword or negative keyword IDs, up to 1000 per call) and, importantly, the literal value confirm='ARCHIVE'. The ad_account_id parameter is left unexplained in both the schema and 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 ('Archive keywords or negative keywords by ID') and names the sibling tool used to obtain the IDs. It is immediately distinguishable from create/update/list keyword 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?

Gives the precondition (IDs come from pinterest_ads_list_keywords) and the user-agreement requirement before confirming. It does not mention alternatives such as pausing via set_statuses instead of an irreversible archive, so it stops short of full 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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine value by disclosing what the entry actually contains (request, response summary, old values of a write), but says nothing about behavior on missing IDs, retention windows, or error responses.

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

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

A single front-loaded sentence with a colon-delimited payload list; every clause carries information and there is no filler or repetition of the tool name.

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

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

For a one-parameter read tool with an output schema and full annotation coverage, the description supplies purpose and return-content semantics adequately. The only shortfall is the absence of sibling routing guidance relative to pinterest_ads_audit_tail.

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

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

With 0% schema description coverage, the description must carry the parameter burden. 'By ID' does clarify that audit_id is the audit log entry identifier rather than an account or campaign ID, which is meaningful, but it gives no format, length, or sourcing guidance.

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

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

The description pairs a specific verb ('Look up') with a specific resource ('an audit log entry by ID') and even names the entry's constituents (request, response summary, old values of a write). It is clearly distinguishable from listing-style siblings, though it does not explicitly name pinterest_ads_audit_tail as the 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?

Usage is implied: call this when you already have an audit ID. However, the description never states the alternative (pinterest_ads_audit_tail for browsing recent entries) or what to do when the ID is unknown, leaving the agent to infer the routing decision from sibling names alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety behavior is covered without the description. The description adds genuine value by stating the log contains dry-run rehearsals as well as writes, but it omits ordering (newest first?), what happens when more entries exist than the limit, and any retention window.

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

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

A single front-loaded sentence with the scoping detail in parentheses; nothing is wasted and the key noun phrase comes first. Appropriate size for a one-parameter read 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, so return-value format need not be explained, and annotations cover the safety profile. Still, for a tool whose only knob is a truncation limit, the definition leaves limit behavior and sibling routing unexplained, which are the two things an agent most needs here.

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 parameter, 'limit', with a default of 20 and 0% schema description coverage, so the description carries the full burden of explaining it. The description never mentions 'limit' at all — no maximum, no statement about the default, and no clarification whether it truncates to the newest N entries. An agent must infer this entirely.

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 ('Show') plus a specific resource ('the most recent audit log entries'), with the added scope clarification that entries cover both writes and dry-run rehearsals. It does not differentiate itself from the sibling pinterest_ads_audit_lookup, so an agent cannot tell from the description alone which of the two audit tools to reach for.

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

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

Usage is implied by 'most recent' (recency-oriented inspection), and the dry-run mention hints at a post-rehearsal verification use case. However, there is no explicit when-to-use statement and no guidance on when to prefer pinterest_ads_audit_lookup instead, which is the obvious alternative in the sibling list.

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

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

Annotations already flag destructive and non-idempotent, and the description adds materially: the 1000-item cap, the confirm='DELETE' requirement for deletions, the confirm='APPLY' requirement above PINTEREST_ADS_BULK_THRESHOLD, and that the call is asynchronous, returning a batch_id to poll with pinterest_ads_get_catalog_items_batch. That is real behavioral context an agent cannot get from the annotations.

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

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

Dense and front-loaded — verbs and cap first, then the item shape, then the feed caveat, then the confirm gates, then the return value. Nothing is filler, though the trailing fragment about the return value reads as tacked on rather than integrated.

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

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

For an eight-parameter, destructive, non-idempotent batch mutation with no output schema and 0% schema description coverage, key gaps remain: the roles of catalog_id vs ad_account_id, what catalog_type defaults to and affects, and what country/language constrain. The operational and confirmation story is complete; the parameter story is not.

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 load. It does well on operation, items (with a concrete example object and the note that DELETE needs only item_id) and confirm, but country, language, catalog_id, catalog_type and ad_account_id get no explanation at all, leaving five of eight parameters undocumented anywhere.

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

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

The description opens with a specific verb set and resource: create/update/upsert/delete catalog items in a batch, with a size ceiling of 1000. That distinguishes it from list/get siblings such as pinterest_ads_get_catalog_items and from the feed-based pinterest_ads_ingest_catalog_feed path.

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 spells out the four operations and what each means in practice (UPDATE changes some attributes, UPSERT sends every attribute), and it names an explicit alternative: if a feed manages the catalog, change items through the feed instead. The confirm gates tell the agent the exact conditions required before a destructive or bulk apply proceeds.

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, and the description reinforces rather than contradicts them ('Changes nothing in the account'). It adds genuinely non-obvious behavior: a single background job, blocking poll-with-progress execution, active-entities-only export scope, and incremental export via updated_since. It omits what happens on timeout or when max_rows is hit.

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: what it does and how it runs come first, then parameter notes. The telegraphic fragment style is efficient, though the 'up to 6 ... CAMPAIGN, ..., SCHEDULE' sentence misfires by listing seven items against a stated cap of six, which costs 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?

An output schema exists, so return values need not be described, and the job/polling model is explained. However, for an 8-parameter tool with 0% schema coverage, the description leaves key operational behavior (poll_seconds, timeout_seconds, max_rows truncation, entity_ids scoping) 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 coverage is 0%, so the description must carry parameter meaning; it covers entity_types (enumerated values), campaign_filter (with a concrete example shape), and updated_since (timestamp semantics). Five of eight parameters — max_rows, entity_ids, poll_seconds, timeout_seconds, ad_account_id — get no explanation at all, and 'up to 6 of' followed by seven listed values is internally inconsistent.

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

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

Names a specific verb and resource ('Export ad entities in bulk') and adds the distinguishing execution model ('one background job', waits with progress, returns rows), which separates it from the many pinterest_ads_list_* siblings. It does not explicitly name an alternative tool, so sibling differentiation is implied 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?

Implies the use case (bulk multi-entity extraction) but never states when to prefer this over pinterest_ads_list_campaigns / list_ads / list_keywords, nor when not to use it. The 'Pinterest exports active entities only' note is a useful usage constraint but is a data caveat, not selection 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?

Well beyond the annotations, it discloses that the job is applied asynchronously in the background, that this server cannot verify every resulting change, that a confirm token of 'APPLY' (or 'ARCHIVE' when anything is archived) is mandatory, and that campaigns created without a status land PAUSED. It also states the return contract (a request_id) and the tool to poll it with. That is exactly the extra risk and side-effect context an agent needs for a destructive, non-idempotent write.

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 purpose, then payload shape, then safety/confirmation, then return value — a sensible progression with no filler sentences. The middle paragraph is dense and slightly run-on, but every clause carries information the caller could not get from the empty-parameter schema.

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

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

For a 4-parameter bulk mutation with an output schema present, the description covers the async lifecycle, the confirmation gate, default status behavior, and the poll target, so an agent can call it correctly. Remaining holes are the unexplained ad_account_id and the absence of any statement about what happens when both create and update are omitted.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning — and it largely does: it explains the shape of 'create' and 'update' as objects keyed by entity family, gives concrete example payloads for product group promotions and keywords, and specifies the confirm values APPLY vs ARCHIVE. The gap is ad_account_id, which is never mentioned, and the fact that nothing says at least one of create/update is expected.

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

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

The first sentence gives a specific verb pair (create and/or update), a specific resource (many ad entities), and a distinguishing mode (one asynchronous Pinterest bulk job). That 'bulk, many entities, one job' framing separates it cleanly from the single-entity siblings such as pinterest_ads_create_campaigns and pinterest_ads_update_ads.

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

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

The description establishes clear context for use: it enumerates the entity families it can batch (campaigns, ad_groups, ads, product_groups, keywords, catalog_product_groups, labels, schedules) and tells the caller that each entry mirrors the matching create/update tool, with updates needing an id. It also names the required follow-up tool (pinterest_ads_get_bulk_request). What it lacks is an explicit 'use this instead of N single calls when...' statement or an exclusion, so the when-not side is left implicit.

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

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

Beyond the annotations (readOnly=false, openWorld=true, idempotent=false, destructive=false), the description discloses the batch mechanics, that items land in PAUSED when status is omitted, the confirm gate for oversized batches/values, the dry-run rehearsal path, and the account-currency micro-unit convention. These are exactly the operational traits an agent needs before mutating a live account.

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

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

The impact and limits are front-loaded in the first line, then parameters and conditional rules follow in short, information-dense sentences. Nothing is filler, though the example payload plus the goal-metadata rules make it longer than strictly minimal.

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

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

For a mutation tool with three parameters, zero schema coverage and an output schema already present, the description covers payload shape, defaults, limits, escalation rules and the dry-run workflow — nearly everything needed to call it correctly. The only omission is what ad_account_id does and when it must be supplied versus inferred.

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 'items' is a free-form object with additionalProperties, so the description carries the full burden — and it does: a worked example, required targeting_spec keys, optimization_goal_metadata shapes per campaign objective, and micro-currency math. The third parameter, ad_account_id, is never mentioned, which is the only real 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 opens with a specific verb and resource ('Create ad groups'), states the batch ceiling (500 per call, 30 at a time) and the side effect ('Changes the live account'), so an agent can immediately tell this apart from list/update/archive ad-group tools. It never names a sibling explicitly, but the create-vs-update-vs-archive distinction is unambiguous from the verb.

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 real routing guidance: use pinterest_ads_get_targeting_options for valid codes, rehearse with dry-run first, and supply confirm='APPLY' for large batches or values above the max budget/bid. It does not state when to prefer this over update_ad_groups, but the create context is clear from the verb and the per-item payload description.

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 side effects of creation: the Pin lands on a protected 'Ad-only Pins' board and cannot be saved by others or shown organically. It also names the required auth scope with the exact command to grant it, and warns that trial-access apps produce Pins only the creator can see — auth, visibility, and side-effect context the readOnly/openWorld hints do not carry.

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

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

Front-loads the verb and resource, then layers on constraints and auth in compact sentences with no filler. Slightly dense and mixes operational instructions (the auth command) with conceptual explanation, but every sentence earns its place.

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

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

An output schema exists, so return values need no explanation, and the description covers the hard parts of a creation tool: auth scope, visibility semantics, and AI-disclosure obligations. The gap is the under-documented optional params, particularly board_id, which sits awkwardly against the stated fact that ad-only Pins live on a protected system board.

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

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

With 0% schema description coverage across 8 params, the description must carry all meaning, and it only covers a subset: ad_account_id (ownership), ai_disclosures (with the valid values AI_MODIFIED and SYNTHETIC_PERFORMER), and image_url implicitly. The remaining params — link, title, alt_text, description, and especially board_id — get no explanation of their role or relationship to the protected ad-only board.

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

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

States a specific verb and resource ("Create an ad-only Pin from an image URL") and immediately gives its downstream role ("to use as an ad's pin_id"), which separates it from pinterest_ads_create_ads and the general Pin/board readers in the sibling list. The follow-up sentence defines what an 'ad-only Pin' actually is, so the agent isn't guessing at the concept.

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?

Explains the context in which this tool is appropriate (ad creative supply, not organic posting) and gives an operational instruction to pass ad_account_id so the Pin belongs to the right profile. It stops short of explicitly routing the agent to pinterest_ads_create_ads as the next step, so the workflow 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?

Adds substantial behavior beyond the annotations: the 30-at-a-time batching, that changes hit the live account, that items without a status default to PAUSED, that Pinterest review gates serving, and that confirm='APPLY' is an escalation gate for large batches and over-max budget/bid values. These are exactly the operational traits an agent needs before invoking a write 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 mutating action and batch limit, then the payload shape, then the review and confirmation rules. Dense and telegraphic in places (e.g. the creative_type list), but nearly every clause carries operational meaning.

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 batch-write tool with an output schema already present, the definition supplies everything else an agent needs: payload shape, Pin ownership requirement, creative_type mapping, default status, review delay, confirmation gate, and dry-run path. No material gap remains for correct invocation.

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

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

Schema coverage is 0%, so the description carries the load — and it does for items, with a full example object, field names (ad_group_id, pin_id, creative_type, name, destination_url), the creative_type enum, and the PAUSED default. It also explains confirm's escalation rule. The ad_account_id parameter, however, is never explained, so the compensation is strong but not total.

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

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

States a specific verb and resource ('Create ads') plus concrete scope (up to 500 per call, sent 30 at a time). The description clearly delineates this from siblings like pinterest_ads_create_ad_pin (which makes the Pin media) and pinterest_ads_create_campaigns/ad_groups.

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

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

Gives actionable when-to-use context: find a Pin with pinterest_ads_list_pins or create one with pinterest_ads_create_ad_pin, rehearse with dry-run first, and use confirm='APPLY' for large batches or out-of-range budgets/bids. It stops short of explicitly contrasting create_ads with pinterest_ads_bulk_upsert or update_ads as the alternative for edits.

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, openWorldHint=true, idempotentHint=false and destructiveHint=false, so the safety profile is known. The description adds real value beyond that by stating "Changes the live account" and by imposing a compliance constraint (use only data you have rights and consents for under Pinterest's Ad Data Terms), which is a behavioral restriction an agent could not infer from structured fields. It still omits permission requirements and validation behavior for malformed rules.

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 blocks: the effect statement first, then a compact per-type rule reference. Every line of the example block supplies distinct, non-redundant information, and there is no filler.

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

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

An output schema exists, so return values need not be explained, and the annotations cover idempotency and safety. For a 5-parameter mutation with a free-form nested object, the description supplies the hardest missing piece (the rule shape per type) plus the live-account and data-rights warnings; only the identity/account parameters remain unaddressed.

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

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

Schema description coverage is 0% and the nested `rule` object is merely additionalProperties:true, so the description carries the full burden here — and it does so well by enumerating the four audience_type values and giving a concrete JSON rule shape for each. It leaves name, description, and ad_account_id (nullable, presumably a default-account fallback) undocumented, which keeps it short of a 5.

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

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

The description opens with a specific verb and resource ("Create an audience for targeting"), which is clearly distinct from sibling operations like get_audience, list_audiences, and update_audience. It does not explicitly name those siblings, but the create-vs-read/update split is unambiguous from the verb alone.

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

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

The audience_type examples imply which kind of audience to build and when each rule shape applies, which is genuinely helpful context. However, there is no explicit routing guidance against alternatives such as pinterest_ads_create_customer_list, update_audience, or estimate_audience_size, and no stated prerequisites (permissions, ad account requirements).

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 past the annotations by disclosing that items without a status are created PAUSED, that changes hit the live account, that requests are throttled 30 at a time within a 500 cap, and that over-limit values require an explicit confirm token. These are exactly the side effects and guardrails an agent cannot derive from readOnlyHint=false / idempotentHint=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?

Front-loads the batch limit and live-account warning, then moves into item semantics, units, and the confirm/dry-run guardrails — a sensible order with almost no filler. It reads as a dense paragraph rather than separated sections, which makes scanning slightly harder, but every sentence carries information.

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

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

For a mutation tool with a free-form item payload and an output schema present (so return values need no explanation), this covers limits, defaults, units, enums, and confirmation requirements. What's missing is the meaning/role of ad_account_id and any note on partial-failure behavior in a 500-item batch.

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 items is a free-form object array, so the description carries the full burden — and it does: it gives an example item, enumerates objective_type values, states the SALES/CONSIDERATION → STANDARD_AD/CATALOG constraint, defines Unix-second timestamps, and defines micro-unit money fields. It also explains the confirm value required. Only ad_account_id is left uninterpreted, which is a minor residual 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 (create campaigns) plus the batch scope (up to 500 per call, sent 30 at a time) and the effect on the live account. The verb makes the split from pinterest_ads_update_campaigns and pinterest_ads_archive_campaigns obvious without needing to open 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 concrete operating conditions: rehearse with dry-run first, and confirm='APPLY' is needed for large batches and values above PINTEREST_ADS_MAX_BUDGET/PINTEREST_ADS_MAX_BID. It stops short of explicitly naming an alternative tool (e.g. bulk_upsert or request) or stating when not to use it, so the agent must infer routing from names 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 only say this is a non-read-only, non-idempotent, non-destructive open-world write; the description adds real behavior: the account is mutated, identifiers are trimmed, lower-cased and SHA-256 hashed server-side unless already hashed, and there is a hard 50,000-identifier cap per call. Those are exactly the side effects an agent cannot infer from the hints.

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

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

Dense and front-loaded: purpose, then mutation warning, then allowed types, then processing behavior and limits, then the next step. The standalone 'Changes the account.' line is terse but deliberate; nothing is redundant, though the paragraph could be broken into tighter lines for scannability.

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 five-parameter write tool with an output schema, the description covers purpose, mutation semantics, accepted types, preprocessing, batch limit, compliance, and the downstream step. Minor gaps: what 'name' is used for and how ad_account_id defaults when omitted.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does for the two most consequential fields: it enumerates list_type values including the EMAIL default, and explains that identifiers are hashed unless already hashed (implicitly tying to hash_identifiers). It leaves 'name' and 'ad_account_id' unexplained, which keeps it short of a 5.

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

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

States a specific verb and resource ('Upload a customer list') plus the accepted identifier domains (emails or mobile ad IDs), which separates it cleanly from pinterest_ads_create_audience, pinterest_ads_update_customer_list and pinterest_ads_list_customer_lists. An agent can pick this tool without opening the schema.

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

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

Gives an explicit follow-up path ('then turn the list into an audience with pinterest_ads_create_audience') and a consent precondition, which frames when the call is appropriate. It does not explicitly contrast against update_customer_list for appending to an existing list, so routing there is 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=false, destructiveHint=false and openWorldHint=true, and the description adds real context beyond them: it warns that the call mutates a live account and documents a confirmation gate for bulk inserts. It still does not say whether existing keywords are merged or replaced, which matters given idempotentHint=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?

Front-loaded with purpose and the live-account warning, then scoped detail on keyword format and match types. The unusual blank-line/stanza layout adds a little noise but nothing is redundant.

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

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

With an output schema present, return values need no explanation, and the description covers the mutation, the input shape, the enum values and the bulk confirmation requirement. The remaining gap is the role of ad_account_id and merge-vs-replace semantics in a non-idempotent write.

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 the load, and it does cover the hardest parameter well: keyword input may be plain strings (using match_type) or objects like {"value": ..., "match_type": ...}, with BROAD/PHRASE/EXACT enumerated and confirm='APPLY' explained. ad_group_id, ad_account_id and the default value of the confirm field are left entirely to the bare schema.

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

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

The description states a specific verb and resource ('Add targeting keywords to an ad group') and makes the effect explicit ('Changes the live account'). It does not name the sibling alternatives (create_negative_keywords, suggest_keywords, list_keywords), so an agent must infer the boundary, but the operation itself is unambiguous.

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

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

Usage is implied by 'Add targeting keywords to an ad group', and the bulk threshold rule ('More than PINTEREST_ADS_BULK_THRESHOLD keywords need confirm=APPLY') gives a concrete precondition. There is no explicit when-not guidance or pointer to sibling tools for listing, suggesting, or adding negative keywords.

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 and destructiveHint=false, but the description adds the material detail that this mutates the live account and that a confirmation token is needed past a bulk threshold — context that isn't in the annotations or schema. It doesn't say whether additions can be reverted or how failures are reported, which keeps it from a 5.

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

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

The effect and the live-account warning are front-loaded in one sentence, followed by tight per-parameter notes with no filler. The line-wrapped parameter block is slightly awkward to scan but nothing is redundant.

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

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

For a 5-parameter mutation tool with annotations and an output schema, the description covers the critical hazards (live changes, bulk confirmation) and the two ambiguous fields. The remaining gap — undocumented ad_account_id and keywords item format — is minor but real given 0% schema coverage.

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 explain parent_id's three levels (ad group / campaign / ad account) and match_type's values and default. However, ad_account_id is never mentioned and the expected shape of the keywords array is left implicit, so it only partially compensates.

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

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

States a specific verb and resource ('Add negative keywords') plus the observable effect ('so ads don't show on those searches'), which cleanly separates it from pinterest_ads_create_keywords and the archive/list keyword siblings. The scope sentence ('Changes the live account') further pins down what kind of operation it is.

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

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

Gives clear context for when this applies (excluding searches) and a concrete prerequisite: bulk requests above PINTEREST_ADS_BULK_THRESHOLD require confirm='APPLY'. It does not explicitly name an alternative tool or say when not to use it (e.g. vs pinterest_ads_create_keywords), so it stops 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?

Annotations already declare this as a non-read-only, open-world, non-idempotent mutation, so 'Changes the account' largely restates readOnlyHint=false. Beyond that, the description discloses nothing about required permissions/scopes, what happens on duplicate names (relevant since idempotentHint=false), or what identifier is returned, which are the behaviors an agent actually needs.

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 prose is two tight sentences front-loading the action and the account-mutation note, and the example earns its space for a free-form nested object. The multi-line JSON wrapping is slightly awkward to parse but contains no filler.

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

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

For a create tool with a nested free-form required object, no output schema, and no documented return value, the definition is only partially complete: it omits ad_account_id handling and any statement of what is returned (e.g., the new product group ID) or the catalog-vs-feed prerequisite chain. The payload example compensates for the biggest gap but not all of them.

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

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

With 0% schema description coverage the description must carry the parameter burden, and it does supply a concrete, annotated product_group example with catalog_id, country, locale, name, and nested filters/all_of clauses. However, ad_account_id is never mentioned, and the filters semantics (all_of, inclusion) are shown only by example rather than explained.

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

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

The description opens with a specific verb+resource: 'Create a catalog product group,' which is clearly distinguishable from the sibling update/delete/list product group tools. It does not explicitly name those alternatives, but the create verb leaves no ambiguity about 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?

Usage context is only implied; there is no explicit 'use this when... do not use this for...' guidance relative to update_product_group or the promotion tools. The one conditional hint ('Feed-based groups use feed_id instead of catalog_id') gives useful branch guidance but is buried inside the payload example rather than stated as a 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?

Annotations already flag a non-read-only, non-destructive, non-idempotent open-world write, so the bar is lower. The description still adds value beyond them: it warns that the live account changes, that items without a status are created PAUSED, and that bids above PINTEREST_ADS_MAX_BID or large batches require confirm='APPLY' — a real safety gate the schema does not express.

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 purpose and blast-radius warning are front-loaded in the first sentence, followed by the example and the confirm rule. Every sentence tightens a decision the caller must make; there is no filler.

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

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

With an output schema present, return values need not be described, and the mutation path, default status, and confirm escalation are all covered. The only real hole is ad_account_id semantics for a tool that touches a live account.

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

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

Schema description coverage is 0%, so the description carries the burden. It does well on 'items' (a worked example with catalog_product_group_id, creative_type, bid_in_micro_currency) and on confirm (APPLY required for oversized bids/batches), but never explains ad_account_id or how ad_group_id is resolved, leaving one of four parameters 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?

The description names a specific verb and resource (promote catalog product groups in an ad group) and parenthesizes the ad product ('catalog ads'), which separates it from the plain create_product_group sibling. It does not explicitly contrast with list/update_product_group_promotions, but the create framing is unmistakable.

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

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

It states a concrete precondition: use with SALES or CONSIDERATION campaigns whose intended_promotion_type is CATALOG. That is a real when-to-use gate. It stops short of naming siblings to use instead (e.g. update_product_group_promotions for edits, set_dry_run for rehearsal).

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'Changes nothing in the account' while adding behavior annotations cannot express: the report is built in the background and requires polling plus a token handoff. It also discloses temporal quirks such as HOUR granularity no longer including conversion metrics, and warns that campaign_objective_types should include SALES and LEADS rather than the retiring values.

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 workflow and the 'changes nothing' reassurance are front-loaded, and the parameter guidance is grouped sensibly (level → dates → granularity → filters → format → template). The long column glossary is genuinely useful for choosing report columns, though it is dense enough to make the description read as a wall of text.

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

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

For an async report-creation tool with 15 parameters and an output schema, the description covers the lifecycle, the sibling handoffs, the level/granularity/format choices, and common column semantics. Attribution-window parameters are the only notable omission, and the pointer to pinterest_ads_list_metrics for full column definitions closes the other documentation loop.

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 full burden, and it does substantial work: valid level values, the ≤5 targeting_types link to *_TARGETING levels, date format YYYY-MM-DD, granularity enum, the shape of filters with concrete campaign_ids/campaign_statuses examples, report_format JSON/CSV, and template_id semantics. Six parameters remain unexplained — ad_account_id, view_window_days, click_window_days, engagement_window_days, reporting_timezone, and conversion_report_time — which is the main gap for a 15-parameter tool.

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

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

Opens with a specific verb+resource ('Request an ads report') and immediately scopes it as an async job rather than an inline result. It distinguishes itself from pinterest_ads_get_report, pinterest_ads_download_report, and pinterest_ads_run_report by naming them and their roles, so an agent can place this tool in a 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 an explicit decision path: call this, poll pinterest_ads_get_report with the returned token, then pinterest_ads_download_report — or use pinterest_ads_run_report to collapse all three. It also names an alternative mode (template_id for saved Ads Manager reports, with a pointer to pinterest_ads_list_report_templates) and the constraints on that mode (dates and granularity only).

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, idempotentHint=true and readOnlyHint=false, so the bar for added context is higher, and the description clears it. It discloses the real-world blast radius (ad groups targeting the audience lose that targeting), states the operation is irreversible, and specifies the exact confirmation token required, plus the human-consent gate.

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

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

Two sentences, both earning their place: the first states the action, the second front-loads consequences and then the confirmation requirement. No filler or restatement of the title.

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

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

For a destructive, irreversible mutation with an output schema that covers return values, the description supplies impact, reversibility, and the confirmation protocol, which is nearly everything an agent needs. The only gap is the role of the optional ad_account_id context parameter.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden, and it does for the one genuinely non-obvious parameter: confirm must equal the literal "DELETE". The audience_id and optional ad_account_id are not elaborated, but their meaning is largely evident from their names.

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

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

The description opens with a specific verb+resource ("Remove an audience"), which is unambiguous against siblings like pinterest_ads_get_audience, pinterest_ads_update_audience and pinterest_ads_list_audiences. It stops short of distinguishing removal from archival semantics, which is the only nearby ambiguity, so it lands just under full marks.

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

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

It gives a clear usage precondition: the call requires confirm="DELETE" and only after the user has agreed, which tells an agent the surrounding workflow. It does not explicitly contrast with update_audience or archive-style alternatives, so it is clear context rather than a full when/when-not rule set.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds real value beyond them: the downstream consequence that ads promoting the group stop, and the irreversible nature of the operation. It also surfaces the confirm-token gate, which appears nowhere in the annotations.

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

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

Two sentences, no filler. The operation and its destructive effect come first, with the confirmation requirement front-loaded in the second sentence.

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

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

For a destructive three-parameter mutation with no output schema, the description covers the essentials an agent needs: consequence, irreversibility, and the confirmation protocol. Only the ad_account_id parameter (likely optional/derived) is left unaddressed.

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

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

Schema description coverage is 0%, so the description must carry the burden, and it only explains one of three parameters — the exact value required for confirm ('DELETE'), which is genuinely useful given the empty-string default. ad_account_id remains unexplained, and product_group_id is only implied by the tool name.

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

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

States a specific verb and resource: 'Delete a catalog product group.' The catalog/product-group scope cleanly separates it from the sibling set (list/create/update_product_group, delete_audience) without ambiguity about what operation is performed.

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 precondition: the call requires confirm='DELETE' and only after the user agrees. It does not name an alternative path (e.g., pause via update_product_group if the user only wants ads to stop), which is the one missing routing hint.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is fully covered. The description adds content scope (API host, default ad account, safety settings) but nothing further about behavior; output details are covered by the output schema, so this is adequate rather than rich.

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

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

A single, front-loaded sentence with no filler. Every element (host, default account, safety settings) carries information about the return payload.

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-argument read-only introspection tool with an output schema, naming the config categories it surfaces is sufficient to call it correctly. Only the relationship to the other diagnostics tools (health_check, audit_lookup) is left unstated.

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

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

The tool takes zero parameters, so there is no parameter semantics for the description to explain. Baseline 4 applies; nothing is misleading or missing.

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?

"Show which API host, default ad account and safety settings this server uses" gives a specific verb plus the exact contents of the report, so an agent knows this is a configuration introspection call. It does not name sibling diagnostics (health_check, audit_lookup) to sharpen the boundary, but the resource is unambiguous.

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

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

Usage is only implied: an agent can infer it should call this to inspect server state before acting. There is no statement about when to prefer it over pinterest_ads_health_check or pinterest_ads_audit_lookup, nor any note that it requires no ad account 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 cover the safety profile (readOnly, idempotent, non-destructive, open-world), so the description's added context is the differentiator: results are held in memory only, and row_count/truncated disclose how truncation to max_rows is signalled. That is useful behavior beyond the structured fields, though it omits what happens on a format mismatch or a non-finished report.

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 download action and scope, then the truncation semantics and format constraint. No redundant restatement of the name or title; every clause conveys information an agent needs.

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

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

An output schema exists, so return values need only be described at the level of row_count/truncated, which the description does. The remaining gap is the undocumented token/ad_account_id parameters and the absence of any note on error conditions for a not-yet-finished report.

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 four parameters, so the description must carry the load. It explains max_rows (via the truncation mechanism) and report_format (must match the original request), but says nothing about token or ad_account_id, leaving half the parameters undocumented anywhere.

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

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

Uses a specific verb (Download) and resource (report) and adds a discriminating qualifier: the report must be FINISHED, which separates it from the sibling create_report/get_report/run_report tools by lifecycle stage. It does not name those siblings explicitly, so the disambiguation is implied 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?

The capitalised FINISHED and the note that report_format must match the requested format imply a pre-condition and a sequencing rule (create/run first, then download). However, there is no explicit when-to-use vs pinterest_ads_get_report guidance and no stated failure behavior if the report is still running.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so 'Changes nothing' largely restates them rather than adding new information. The description does add the useful behavioral framing that this is a prospective reach estimate rather than a stored audience, but says nothing about result variance, latency, or minimum audience thresholds.

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

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

Two short sentences, front-loaded with the purpose, followed by compact inline examples that earn their space. The trailing example block is slightly terser than it could be but contains no filler.

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

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

With six parameters, nested objects, and zero schema description coverage, the definition should do more: four optional parameters are undocumented and there is no note on what the estimate response contains beyond the existence of an output schema. It is adequate for the required parameter but incomplete for the full surface.

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 six parameters, so the description carries real weight, and it correctly supplies concrete examples for targeting_spec and keywords shapes. However, ad_account_id, creative_types, product_group_ids and auto_targeting_enabled are left entirely unexplained in both schema and description, leaving the compensation partial.

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

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

'Estimate how many people an ad group's targeting would reach' is a specific verb plus resource and clearly separates this tool from the creation/mutation siblings (create_ad_groups, get_audience). It does not explicitly name a sibling to contrast with, so it stops short of a 5.

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

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

Mentioning 'targeting_spec as in ad group create' implies the pre-flight/validation workflow before creating an ad group, but there is no explicit when-to-use, when-not-to-use, or named alternative such as get_audience_insights. 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered elsewhere. The description adds the returned field set as context but says nothing about the effect of a null/missing ad_account_id, required access/permissions, or error behavior for an unknown ID.

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 the core action stated first. The trailing field list arguably duplicates the output schema, which is minor waste but does not obscure the purpose.

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?

Because an output schema exists, the description need not enumerate return values, and annotations cover safety, so the tool does not need a long description. However, for a lookup keyed on an optional, nullable ID, the definition should clarify how the target account is resolved when the parameter is absent.

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 parameter, so the description carries the full burden and fails to compensate: ad_account_id is never mentioned. The listing of returned fields describes output, not the input, which is already covered by the output schema. The nullable-with-null-default behavior of the identifier is left entirely unexplained.

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

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

"Get one ad account" states a specific verb and singular resource, and the qualifier "one" implicitly separates it from the sibling pinterest_ads_list_ad_accounts. The field list (name, currency, country, time zone, owner, permissions) further pins down what is returned, though the sibling is never named 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?

There is no when-to-use guidance: nothing says to call this when you already have an ad account ID versus calling pinterest_ads_list_ad_accounts to discover one. It also gives no prerequisites or hint about what happens when ad_account_id is omitted, despite that parameter being nullable with a null default.

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

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

Beyond the readOnly, idempotent, and non-destructive annotations, the description adds substantial behavioral detail: synchronous execution, the 250-entity limit, default attribution windows, reporting timezone behavior, conversion_report_time options, and the caveat that HOUR granularity no longer includes conversion metrics. It also explains metric naming conventions such as _1 paid versus _2 earned.

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

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

The description is front-loaded with purpose, scope, and key constraints, and the line breaks make the dense parameter guidance readable. It is necessarily detailed for a 14-parameter tool with no schema descriptions, though the long common-column list could be slightly leaner given the explicit pointer to pinterest_ads_list_metrics.

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

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

For a complex analytics tool with no output schema and no parameter descriptions, the definition supplies enough context to call it correctly: scope, required ids, date format, granularity, attribution defaults, timezone and conversion settings, column examples, and known limitations. A few optional parameters and response-shape details remain unaddressed, keeping it short of 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?

With 0% schema description coverage, the description compensates well by explaining level values, date format, granularity values, targeting_types examples and exclusions, attribution window defaults, reporting timezone choices, and column semantics. It still leaves some optional parameters such as ad_account_id and the explicit attribution window/type parameters less directly explained.

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

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

The description uses a specific verb and resource, 'Get ads metrics', and immediately states the scope: synchronous metrics for an ad account or up to 250 campaigns, ad groups, ads, or product groups. It also distinguishes the operation from report-style workflows by emphasizing 'right away (synchronous)' and 'Changes nothing'.

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

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

It gives clear usage context by specifying synchronous retrieval, supported levels, id requirements, date formats, granularity choices, and some exclusions such as targeting_types not being for product groups. It does not explicitly compare itself with asynchronous siblings like create_report or run_report, so the when-to-use-versus-alternatives guidance is clear but not complete.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is fully covered. The description's only addition is a recap of returned fields, which duplicates the output schema rather than adding behavioral context (not-found behavior, account scoping, or access requirements).

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, front-loaded with no filler. It is efficient, though the brevity borders on under-specification rather than true conciseness.

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

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

The output schema exists, so not explaining return shape in detail is acceptable. However, with zero schema documentation on both parameters and no usage routing among four audience-related siblings, the definition leaves the agent without enough to call this confidently.

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 two parameters, and the description says nothing about either. It never explains that audience_id identifies the audience being fetched or what ad_account_id is for or when it is needed.

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 ('Get one audience') and identifies the fields returned (type, rule, size, status). 'One' implicitly contrasts with the sibling list_audiences, though that contrast is never made explicit.

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

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

No guidance on when to use this instead of pinterest_ads_list_audiences, pinterest_ads_get_audience_insights, or pinterest_ads_estimate_audience_size. No mention that ad_account_id may be required for some audience types, so the agent has no conditions to reason about.

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 read-only, idempotent, non-destructive operation. The description adds valuable behavioral context by specifying the 30-day window and aggregated-only limitation, but it says little about data freshness, rate limits, or response structure.

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

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

The description is short, front-loaded, and wastes little space. The parameter explanation is useful, though the formatting is somewhat fragmented.

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

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

For a simple read-only insights tool, the description covers the key data scope and one parameter well. It is still incomplete because ad_account_id is undocumented and there is no output schema to clarify return values.

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 fully documents the audience_insight_type values and default, which is valuable, but it does not explain ad_account_id or its optionality.

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

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

The description clearly states the resource and scope: interests and demographics of the account's audience over the last 30 days. It does not explicitly distinguish this from nearby sibling tools such as pinterest_ads_get_audience or pinterest_ads_estimate_audience_size.

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

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

It gives a useful exclusion: aggregated data only, not for competitor or platform benchmarking. However, it does not explain when to choose this over sibling audience or analytics tools.

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

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

Annotations already cover readOnly, idempotent, non-destructive and open-world, so 'Changes nothing' is largely redundant. The description does add genuine behavioral context: results are in micro-units (1.00 = 1000000) and targeting_spec follows the same shape as ad-group create, which matters for interpreting and constructing calls.

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?

Purpose is front-loaded in one sentence, followed by a short param note and example. The example earns its place, though the two-sentence split around the example is slightly awkward rather than maximally tight.

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 key param is illustrated. Still missing is any treatment of ad_account_id and any explicit routing relative to adjust_ad_group_bids, which an agent needs to sequence bid-floor lookup with bid changes.

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 load. It gives a concrete example object for the required bid_floor_specs and explains the micro-unit convention, but says nothing about ad_account_id and only one clause for targeting_spec, so the compensation is partial.

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

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

States a specific verb and resource ('Get the minimum bids Pinterest accepts for ad groups') and adds a scope note ('Changes nothing') that separates it from the bid-mutating siblings like adjust_ad_group_bids. It does not name a sibling explicitly, so it stops short of the top mark.

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?

'Changes nothing' implies this is the read-only way to learn the accepted floor before setting bids, and it notes targeting_spec is 'optional, as in ad group create'. But there is no explicit when-to-use/when-not guidance or named alternative, leaving the agent to infer the workflow.

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

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

Annotations already establish read-only, idempotent, non-destructive, open-world behavior, and the description adds genuinely new context: the three terminal/intermediate states, the fact that a result file is only fetched when download=true AND status is SUCCEEDED, and that rows are held in memory only (i.e. not persisted). It does not say what happens if download=true while status is still RUNNING, nor whether max_rows truncates silently.

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

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

Two short sentences, front-loaded with the status enumeration, with no filler. The second sentence is slightly dense in packing the download gate, the status precondition, the row cap, and the memory-only caveat into one clause.

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

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

The output schema relieves the description of explaining return shape, and the status/download semantics are covered. However, for a five-parameter tool with zero schema coverage, leaving ad_account_id and include_details unexplained and not describing behavior when max_rows truncates or when download is requested on a non-SUCCEEDED job leaves real gaps.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains download and max_rows (a row cap, in-memory) and implies request_id is the bulk job identifier, but says nothing about ad_account_id or include_details, two of the five parameters. Half the surface remains undocumented in both schema and description.

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

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

The description names a specific resource (“bulk upsert or bulk export”) and a specific operation (fetching its status), and enumerates the possible states RUNNING, SUCCEEDED, FAILED. It implicitly pairs with the bulk_upsert/bulk_export siblings but never names them as the tools that create the request_id being polled, so routing 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?

The download=true condition combined with status SUCCEEDED gives one concrete conditional path, but there is no explicit statement that this is the polling tool to call after pinterest_ads_bulk_export or pinterest_ads_bulk_upsert, nor guidance on when to stop polling or how it differs from read_request. Usage is implied rather than prescribed.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so 'Changes nothing' is largely redundant. The genuinely additive detail is the 'Up to 100 item IDs' batch ceiling and the accepted country/language formats, which are behavioral constraints not present in the annotations or schema.

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

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

Very short and purpose-first, which is good, but the second paragraph is a dangling fragment with no subject ('country e.g. ... language e.g. ...') that reads as a stripped schema hint rather than a sentence. It could be reformatted as one clear sentence about accepted formats and the 100-ID cap.

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 6-parameter tool with zero schema coverage and no output schema, the definition covers only the three required parameters. It never explains when catalog_id or ad_account_id must be supplied or what catalog_type='RETAIL' means, and it doesn't distinguish this tool from the batch item siblings, leaving real ambiguity.

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

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

Schema description coverage is 0%, so the description carries the burden. It clarifies item_ids (feed id column, max 100), country ('GB') and language ('en-GB'/'EN') formats, but leaves catalog_id, catalog_type (default RETAIL) and ad_account_id completely unexplained, which is half the 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?

States a specific verb and resource ('Look up catalog items by item ID') and adds the useful disambiguation that the ID is the feed's 'id column'. It does not name the closely related siblings (get_catalog_items_batch, batch_catalog_items), so an agent must infer which lookup variant to use.

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 when-to-use guidance and no exclusions. With several sibling tools operating over the same catalog item space (batch_catalog_items, get_catalog_items_batch, list_item_issues), the description never says when this single-batch lookup is preferred over those 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 read-only, idempotent, non-destructive, open-world behavior, so the description's job is lighter. It adds useful return-content context (finished flag, per-item errors) but says nothing about polling cadence, retention of batch results, or what happens for an unknown/expired batch_id.

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

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

A single tight sentence with the key information (status, errors) front-loaded and no filler. It is arguably too terse for a tool with two undocumented parameters, but nothing in it is wasted.

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

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

With no output schema the description usefully sketches the return payload (finish state, per-item errors), which covers the most important gap. However, for a tool with 0% schema description coverage and an unexplained optional account parameter, the definition is thinner than the tool's surface warrants.

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 both parameters rely entirely on the description, which mentions neither. batch_id is required and reasonably self-evident, but the optional ad_account_id is left completely unexplained—an agent cannot tell whether it is needed for scoping or when to omit it.

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

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

The description names the resource (an item batch) and the specific information returned: completion status plus per-item errors. That is far more informative than a restatement of the name, though it never explicitly distinguishes it from the sibling that creates batches (pinterest_ads_batch_catalog_items).

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

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

Usage is only implied: an agent can infer this is the poll-after-submit counterpart to pinterest_ads_batch_catalog_items, but the description never says when to call it, whether it should be polled until finished, or how it differs from pinterest_ads_list_item_issues.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered by structured data. The description contributes only the shape of the returned record; it adds nothing about authentication requirements, rate limits, or what happens when the tag is missing or inaccessible.

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; the verb and resource come first and the returned fields follow as a compact enumeration. Nothing could be removed without losing information.

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

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

For a simple two-parameter read tool with full annotation coverage and no output schema, the description is nearly sufficient: it tells the agent what comes back and implies the lookup-by-ID pattern. The gap is the undocumented ad_account_id and the lack of any note on behavior for missing tags, which is meaningful given 0% schema description coverage.

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, and it does not: it never explains that conversion_tag_id is the identifier of the tag to retrieve nor what ad_account_id is for, why it is optional, or that it defaults to null. The only partial mapping is the word 'tag' implying the ID selects a tag, leaving the optional account-scoping parameter entirely undocumented in both schema and description.

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

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

The description states a specific verb and resource ('Get one conversion tag') and enumerates the returned fields (name, status, last fired time, configuration), which clearly separates it from a bulk-list operation. It does not explicitly name the sibling pinterest_ads_list_conversion_tags, but the singular 'one' paired with a required ID makes the distinction obvious.

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

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

Usage is only implied: 'Get one' combined with a required conversion_tag_id suggests fetching a single known tag rather than enumerating tags. There is no explicit when-to-use versus list_conversion_tags, no mention of prerequisites such as permissions or account scope, and no guidance on error behavior for an unknown ID.

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

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

Annotations already cover the safety profile (read-only, idempotent, non-destructive, open-world), so the bar is lower. The description adds genuinely useful behavior: monthly granularity, a hard cap of 2000 keywords per call, and that results are aggregated across Pinterest rather than scoped to an ad account.

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

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

Two short sentences with the core metric front-loaded and the constraint and usage hint following. No filler, though the parenthetical country examples are largely schema-redundant.

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

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

An output schema exists, so return values need not be described, and the description covers granularity, limits and aggregation. The only real hole is the unaddressed ad_account_id parameter, which conflicts conceptually with the 'aggregated across Pinterest' framing.

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 successfully clarifies country_code (single country, examples 'GB'/'US') and the keywords limit, but leaves ad_account_id completely unexplained — and that omission is especially confusing since the description says results are aggregated across all of Pinterest, implying the account id has no effect.

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 specific metric (monthly search volume), the platform (Pinterest), the scope (one country) and its intended use (sizing keyword ideas). That distinguishes it from the discovery-oriented sibling suggest_keywords, though it never names that sibling explicitly.

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

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

"Use it to size keyword ideas" gives a clear positive cue for when to call it, but there is no explicit contrast with pinterest_ads_suggest_keywords or pinterest_ads_list_keywords, so the agent must infer which keyword tool to reach for in a given situation.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds that finality is per-date, hinting at eventual consistency of metric data, but it does not say what the response looks like, whether a non-final state is retryable, or how long settling typically 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?

A single sentence fragment with zero filler, and the key constraint (date-scoped finality) is front-loaded. The lack of an explicit verb makes it read slightly like a title restatement rather than an instruction.

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

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

There is no output schema, so the description is the only place the return value could be explained, and it never says whether the result is a boolean, a status string, or per-metric flags. For a one-parameter polling-style tool this is a real gap an agent would feel at call time.

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 the parameter, and it does supply the YYYY-MM-DD format that the schema's bare string 'Date' lacks. It leaves open what the date refers to (report date vs. event date) and which timezone applies, which matters for a readiness check.

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

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

The description names a specific resource (conversion and other metrics) and a specific check (whether they are final yet) scoped to a single date, which is distinguishable from the sibling metrics tools like list_metrics and get_analytics. It never explicitly contrasts itself with those siblings, so an agent must infer the boundary.

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 when-to-use statement, no mention of when the answer is not useful, and no named alternative. The implied workflow (call this before trusting metrics for a date) is left entirely 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 establish read-only, idempotent, non-destructive, open-world behavior, so the bar is lower, yet the description still adds meaningful context: a dated permission gate (PINNER_DATA_ACCESS_DENIED for apps registered on or after 14 September 2026) plus an explicit instruction not to retry. That is exactly the kind of failure-mode guidance annotations cannot express. It does not describe pagination or rate-limit behavior, which is minor here.

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

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

Two tight sentences with no filler: the first front-loads what is returned, the second front-loads the parameter rule and then the error contingency. Nothing repeats the tool name or title, and no sentence could be dropped without losing information.

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

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

With an output schema present, the field list is technically redundant, but it usefully previews shape without cost. The two-parameter surface is fully accounted for and the notable failure mode is documented. The only gap is sibling disambiguation, which matters given a crowded pin-related toolset.

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 both parameters are bare strings in the schema, so the description carries the burden. It explains the conditional, optional nature of ad_account_id (only when the Pin belongs to that ad account's profile), which the schema does not convey at all. pin_id is left as self-evident; it could have noted where a pin_id is obtained.

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

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

The description opens with a specific verb and resource ("Get one Pin") and enumerates what comes back (title, link, media, board, promoted status), which is far more informative than the name alone. It never names the nearby siblings (list_pins, list_board_pins), so an agent must infer that this is the single-record fetch rather than a listing call.

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

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

It gives a concrete conditional rule for ad_account_id ("Pass ad_account_id when the Pin belongs to that ad account's profile") and a clear do-not-retry directive for the 403 case, which is real usage guidance. It stops short of saying when to choose this over list_pins or list_board_pins, or what to do if the pin_id is unknown.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety is covered. The description adds nothing beyond that: no note on whether the count reflects all products, only active/approved ones, or whether it is subject to pagination or rate limits.

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

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

Extremely short and front-loaded, but the brevity comes from under-specification rather than economy. As a grammatically incomplete sentence it reads more like a title than an instruction.

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

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

No output schema exists, yet the description does not state that the response is a numeric count or how it is shaped. With a 0%-documented two-parameter schema and no behavioral detail, an agent lacks what it needs to call this confidently.

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 two parameters, so the description carries the full burden and fails. It implies a product group identifier is required, but never explains product_group_id's format or why the optional ad_account_id exists or when to supply it.

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

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

The fragment identifies the resource (product group) and the operation (counting products), so an agent can roughly tell it apart from pinterest_ads_list_product_group_products, which enumerates rather than counts. But it is a noun phrase rather than a verb-led statement, and it never says what is being returned or against what scope.

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

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

There is no guidance on when to use this instead of list_product_group_products, list_product_groups, or get_analytics. The only implied usage is 'you want a count', which the agent must infer from a four-word 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?

The annotations clearly declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, and the description is consistent with a read-only status check. Still, the description does not clarify polling behavior or response semantics beyond the status list, leaving some behavioral expectations implicit.

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

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

The description is compact and easy to scan, with a clear status list and actionable next step. The line break after the period and the sparse detail are minor issues, not verbosity.

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

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

For a simple two-parameter status check, it covers purpose, status values, annotations, and a follow-up tool. However, it omits parameter meanings, especially ad_account_id, and gives no guidance for non-FINISHED states, so it is not fully complete.

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

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

Schema description coverage is 0%, and the description does not define the required token parameter beyond saying "same token" or explain the optional ad_account_id. It adds little parameter semantics beyond linking token to the download_report follow-up.

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 explicitly states "Check a report's status" and enumerates the possible status values: IN_PROGRESS, FINISHED, FAILED, CANCELLED, and EXPIRED. The tool name and title reinforce this purpose clearly.

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

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

It provides an important conditional next step: when the status is FINISHED, call pinterest_ads_download_report with the same token. However, it does not explain when to call this tool initially, where the token comes from, or how to handle non-FINISHED statuses such as polling or retry behavior.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior context — that the returned lists are often long and that search narrows them — but says nothing about how max_results caps the result or whether the call needs an ad account for certain targeting types.

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 allowed values, then the search behavior. The opening fragment ('Valid values for an ad group targeting_spec field.') is slightly clipped but every sentence carries information.

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

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

For a read-only enumeration lookup with an output schema present, the description covers the essential decision inputs: which targeting_type values are legal and how to narrow long lists. The remaining gap — whether ad_account_id is mandatory for audience targeting types — is meaningful but secondary given the 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 0%, so the description carries the full burden. It does well on targeting_type (all ten legal values) and on search (with a concrete example), but max_results and ad_account_id are never mentioned, leaving half the parameters undocumented in either structured or prose form.

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 the resource precisely: valid enumeration values for an ad group targeting_spec field, and enumerates the ten accepted targeting_type values, which lets an agent recognize it as a lookup/enumeration tool. It stops short of an explicit verb phrase and never contrasts itself with nearby siblings such as list_targeting_templates or estimate_audience_size.

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 rather than stated: an agent can infer this is the tool to call to discover legal values before writing a targeting_spec. The search example (search='united kingdom') gives useful invocation context, but there is no explicit when-not guidance and no named alternative for template- or audience-size-related needs.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds value beyond that by disclosing the dual behavior (token owner vs. ad-account owner) and the shape of the returned identity fields, though it omits failure behavior for an unknown ad_account_id.

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

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

Two short sentences with zero filler; the primary behavior comes first and the parameter-driven variant second. Nothing is repeated from the title or annotations.

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

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

For a one-optional-parameter read tool with a full annotation set and an output schema, the description covers purpose, return fields and the parameter's effect. Remaining gaps are minor: ID format, permission requirements, and behavior on an invalid or inaccessible ad_account_id.

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

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

Schema description coverage is 0%, so the description must carry the single parameter, and it does: ad_account_id switches the lookup to the owner of that ad account rather than the token's account. It does not specify the expected ID format (numeric vs. prefixed) or whether the account must be accessible to the token, leaving a small 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 ('Get the Pinterest account behind the token') and even enumerates the returned fields (username, account type, business name). It also clarifies the alternate mode triggered by ad_account_id, which implicitly separates it from siblings like pinterest_ads_get_ad_account and pinterest_ads_list_ad_accounts, though it never names them explicitly.

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

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

The description explains the two usage modes (no argument vs. with ad_account_id), which is real when-to-use guidance. However, it never states when an agent should prefer pinterest_ads_get_ad_account or pinterest_ads_list_ad_accounts instead, nor any prerequisites such as required token scopes.

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 readOnly, idempotent, non-destructive and open-world behavior, so the bar is lower. The description still adds real value by disclosing what the call returns beyond a boolean: granted scopes and rate-limit headers. It does not say what happens if the token is expired or invalid (error vs. refresh), which is the main behavioral unknown for a health check, and 'refresh the access token' sits slightly uneasily with readOnlyHint even though it is defensible as an auth handshake rather than a data write.

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

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

Two short sentences, front-loaded with the 'check the setup' framing and then the concrete steps. No filler. The secondary sentence about scopes and headers is important content rather than padding, though it could have been folded into a single list for faster scanning.

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 with no parameters the call surface is trivial. The description covers the sequence of actions and the diagnostic outputs, which is enough to invoke the tool correctly. The remaining gap is routing: nothing tells an agent when to prefer this over the dedicated account-listing and user-account 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?

The tool takes zero parameters, so there is no parameter meaning to add; the schema is empty and fully described. Baseline for a zero-parameter tool applies, and nothing in the description misleads about inputs.

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 specific verbs and resources: refresh the access token, read the signed-in account, list the ad accounts it can use, and report scopes and rate-limit headers. That is far more informative than the title. However, it never distinguishes this tool from its close siblings pinterest_ads_list_ad_accounts and pinterest_ads_get_user_account, which an agent could easily pick instead.

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?

'Check the setup' implies a first-step diagnostic used before other calls, but the description never states that condition explicitly, gives no exclusions, and does not mention the two sibling tools that overlap with its listing behavior. Usage is inferable but not spelled out.

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 operation is not read-only, not idempotent, and open-world, so the agent knows it causes a side effect. The description adds that the work is delegated asynchronously to Pinterest, but it doesn't say whether the call returns immediately, whether repeated calls re-fetch, or what the response contains — meaningful gaps for a non-idempotent trigger.

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

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

One sentence, front-loaded with the action and contrasted against the default scheduling behavior. Nothing redundant.

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

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

For a two-parameter trigger with no output schema, the description should at least hint at the async nature of the result and how to verify processing (a dedicated sibling exists for feed processing results). Annotations cover the safety profile, but the post-call workflow is not addressed.

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 neither parameter is mentioned. 'feed_id' is inferable from the tool name, but 'ad_account_id' (optional, nullable, default null) is completely unexplained in both schema and description, so the description does not compensate for the coverage gap.

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

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

The description names a specific action (triggering a fetch/processing of a catalog feed) and frames it against the default behavior (waiting for the schedule). That's enough to distinguish it from siblings like list_catalog_feeds and list_feed_processing_results, though it doesn't name them 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?

It gives a clear trigger condition: use this when you want processing to happen now rather than on the normal schedule. It stops short of stating exclusions (e.g., don't spam repeated triggers, or use list_feed_processing_results to check the outcome afterward).

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

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world behavior, so the safety profile is covered. The description adds the meaningful nuance that shared/agency accounts are included by default and lists the fields returned, but omits pagination behavior and any cap on results, which matters for a list endpoint with a 200 default.

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

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

Two compact sentences, front-loaded with the action and scope, with zero filler. The returned-field list is the only borderline element and is short enough to earn 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?

A simple two-parameter read tool with annotations covering safety and an output schema covering return shape; the description supplies scope and sharing semantics on top of that. The only real gap is pagination/result-cap behavior for max_results, which is minor for this complexity level.

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 partially does: 'by default, ones shared through business access' explains what include_shared_accounts toggles and its default. The max_results parameter is never mentioned, leaving page size and truncation behavior undocumented in both schema and description.

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

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

States a specific verb and resource ('List the ad accounts') plus the precise scope: accounts usable by this token, split into owned and business-shared. This clearly separates it from the singular sibling pinterest_ads_get_ad_account without the agent needing to open 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?

The phrase 'by default, ones shared through business access (agency and partner access)' implies when shared accounts appear, which is useful. However, there is no explicit guidance on when to call this versus get_ad_account, list_businesses, or list_business_assets, and no stated exclusions or preconditions.

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/idempotent/non-destructive, but the description adds high-value behavior the annotations cannot: statuses are filtered by default so archived entities are silently omitted unless widened, IDs match in any status, and results are capped at max_results. It also flags summary_status as a delivery signal, though it says nothing about pagination or ordering.

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?

Purpose is front-loaded in one sentence followed by terse filter notes; nearly every clause carries information. The compressed phrasing ('this entity's IDs', 'where supported') trades a little clarity for brevity.

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 detail is unnecessary, and the description still adds the delivery-signal hint. For a six-parameter list tool with zero schema descriptions, the unexplained ad_group_ids parameter is the main remaining hole.

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 there are 6 parameters: description explains ids (cap of 250), statuses (defaults and allowed widening), max_results and campaign_ids. It leaves ad_group_ids completely unexplained and never resolves how 'ids' relates to the separate ad_group_ids parameter, and ad_account_id is only implied by the phrase 'in an ad account'.

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