Adrails

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds only the cost trait (credit-free calls); it says nothing about pagination behavior despite a cursor parameter existing in the schema.

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

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

Two short sentences, zero filler, with the resource and returned fields front-loaded before the cost note. Nothing is wasted.

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

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

No output schema exists, so the description compensates by naming the fields returned (timezone, currency, freshness, enabled state). Minor gap: pagination and the fact that results are workspace-scoped are left to the schema.

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

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

Schema description coverage is 75%, with 'after', 'accountIds', 'userStatement' and 'idempotencyKey' all documented in the schema itself. The description adds no parameter guidance, so the baseline of 3 applies.

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

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

The description gives a specific verb ('List') and resource ('connected ad accounts') and even enumerates the fields returned (timezone, currency, freshness, enabled state). It does not name a sibling to contrast with, but no sibling in the list covers connected accounts, so disambiguation is largely moot.

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

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

The description implies when to use it (to see which ad accounts are connected), and the 'Free: no Adrails credits' note is a genuine selection signal. However there are no explicit when-not conditions or pointers to alternatives such as integrations_status or channels_manage.

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

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

Annotations already establish a safe read (readOnlyHint=true, destructiveHint=false), and the description still adds real behavior: page size caps and defaults (max 10, default 5), paging with nextOffset under the same account scope, and the no-credits note. Minor flaw: it instructs use of 'nextOffset', while the schema exposes only 'offset', which could confuse an agent on retry/paging.

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 what the tool returns, then usage rules, then mechanics — a sensible ordering. It is dense and directive but nearly every clause carries operational meaning; the trailing MCP/credits sentences are boilerplate that dilutes focus slightly.

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 fully covers the return shape (ids, evidence, state, conditional undo, multi-window observations) and the pagination envelope an agent needs. For a read-only listing tool, nothing material about calling it correctly is missing.

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

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

Schema coverage is 75%, so the schema does much of the work, but the description adds the default page size of 5 (not present in the schema, which only sets a maximum of 10) and the paging rule tying offset to account scope. The showTable semantics are restated rather than expanded, and it says nothing about limit/offset beyond pagination.

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

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

The opening sentence names a specific resource and enumerates its payload: proposed/executed actions, ids, evidence, execution state, undo availability, and 24h/3d/7d observations. That makes the tool's output distinguishable from generic performance tools, though it never explicitly separates itself from plausible siblings like changes_review or findings_review.

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 concrete triggers ('read before an undo', 'when reporting what Adrails changed') and an explicit inverse ('For performance questions, read as background evidence without showTable'). It also gives a narrow condition for showTable=true ('only for an explicit request to display the action history itself'), 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 cover read-only, idempotent and non-destructive behavior, and the description adds real value on top: the caveat that results are estimates, not measured performance, and the cost note (no Adrails credits). It omits latency, failure modes for invalid targeting, and any rate-limit context.

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, purpose front-loaded, caveat second. The credits sentence is minor but relevant to call-cost decisions; 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?

No output schema exists, so the description should say more about the shape of an estimate (single reach figure vs range, breakdown by audience component). It also omits what happens with invalid or unserviceable targeting, leaving meaningful gaps for a nested-schema estimation tool.

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

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

With 75% schema coverage, the baseline is 3. The description adds nothing about the nested input fields — notably the opaque genders enum (1/2) and the countries vs locations distinction — so the schema carries the full parameter burden.

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: 'Estimate Meta reach for proposed targeting.' An agent can distinguish this from sibling listing tools like targeting_options, though no sibling is 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?

Implies usage (pre-launch reach check for proposed targeting) via 'proposed targeting' and 'existing account audience service,' but never states when to use this versus targeting_options or planning_calculate, nor any exclusions or prerequisites.

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

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

Goes well beyond the annotations by stating it runs no model, saves nothing, returns a link for review, and consumes no credits. The readOnly/openWorld/idempotent hints are already covered, but the no-model/no-persistence/no-cost disclosures are genuinely useful additions an agent would otherwise have to assume.

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

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

Front-loaded with the core verb and resource, but it is one dense run-on paragraph. The parenthetical catalogue of brand-profile sections (overview, story, products, audience, positioning...) is long and only marginally helps the invocation decision.

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 four parameters, a nested input object, no output schema and only hints for annotations, the description supplies what's missing: return shape (source address and text, theme visual identity), persistence behavior, and cost. An agent has enough to call it correctly and interpret the result.

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 75%, and the description compensates by explaining the behavioral consequence of omitting 'store' (the call lists stores) and the exact precondition for 'url', neither of which the schema descriptions state as clearly. The generic accountIds/userStatement/idempotencyKey params remain unaddressed but are shared boilerplate.

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 ('Reads one of the workspace's stores') and scopes it to a connected Shopify store or a public URL. It also states what comes back (store details, best-selling products, public pages, theme logo/colors/fonts), which separates it from the store_products/store_orders data siblings, though it never names those siblings 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?

Gives clear conditional routing: pass 'store' when several stores are connected, omit it to get a list, and use 'url' only when the named site isn't a connected store or no Shopify store exists. These are actionable selection rules, though no explicit 'use X instead when...' exclusions against the store_* or site_brief siblings.

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

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

Goes well past the annotations: states no writes and no guessed amounts, discloses pagination, specifies the comparison basis (latest two complete seven-day windows in account timezone), notes missing targets stay missing, warns that delivery targets are not profit, and lists what the report contains. Annotations already cover the safety profile, and the description still adds substantive behavioral context.

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 action, but the body is a dense chain of comma-spliced clauses ('Resolves the event and any cost-cap/minimum-ROAS delivery target from actual ad-set settings, never from generic results or its name') that take re-reading. The trailing MCP/credits boilerplate adds length without aiding tool selection.

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

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

With no output schema, the description compensates by explaining that answer returns a report the agent writes the reply from and that the result includes gaps, evidence and a review point. It also flags read-only, no-guess behavior. Only the pagination/limit semantics and how multi-account runs are batched via evidence mode remain thin.

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?

Adds meaning beyond the 75%-covered schema by explaining the entityId/entityType pairing rule (omit both to discover owners, supply both to scope to one campaign/ad set) and by framing accountId/responsemode semantics in task terms. The limit/offset pagination pair and userStatement/idempotencyKey relevance are not addressed, which is acceptable for a read-only tool but leaves a 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 opening states a specific verb and resource: evaluate budget-owning entities in one selected account and classify them maintain/increase/reduce/investigate. That is concrete and distinguishable from generic diagnostic siblings, though the opaque preamble 'After reading scaling-decision' and the dense middle sentences blur the core purpose. No sibling is named as the near-miss 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?

Gives real usage conditions: omit entityId/entityType to discover owners rather than guess IDs, supply both to review a single campaign/ad set, and read recent changes and constraints before approval. It also explains when to pick answer vs evidence. It never names a sibling tool (e.g. planning_calculate, performance_diagnose) as the alternative, so routing is left partly 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 mark this read-only, idempotent and non-destructive, but the description adds material behavior: it checks quotation provenance without certifying business meaning, requires exact verbatim quotes for supplied numbers, forbids inventing inputs, requires matching currency/definitions/windows, and notes that calls are free. This is consistent with readOnlyHint.

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 front-loads context and critical constraints, and nearly every sentence carries a rule. However, it is a dense run-on paragraph with meta MCP/credits text, making it harder to scan than ideal for an agent.

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

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

For a complex nested-input tool with no output schema, the description supplies the missing behavioral contract: provenance rules, optional omissions, answer versus evidence modes, and no writes or forecasts. Remaining field details are covered by the 75% 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 75%, so the schema carries much of the field documentation. The description still adds critical semantics for review inputs: missing values are optional, every supplied number needs an exact quote, generic AOV is not verified net revenue, pacing uses complete elapsed days, and sources must match before combining. It does not add much beyond the schema for accountIds, userStatement and idempotencyKey, so it is not a full 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 that it provides a bounded explanation/calculation from explicit inputs after unit-economics, revenue-reconciliation or budget-pacing, and the schema's review.type enumerates those modes. It is more specific than a generic review tool, but it does not explicitly distinguish itself from sibling review or diagnostic 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?

Names the triggering analyses (unit-economics, revenue-reconciliation, budget-pacing), gives the exclusion 'No writes or forecasts', and explains the answer versus evidence response modes. It lacks explicit naming of alternative sibling tools for overlapping review work.

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 annotations, the description discloses important behavior: save stores a draft without publishing, delete removes only unpublished drafts and returns an undo ID, list is capped at 100 drafts, validation is required before publication, and MCP calls consume no Adrails credits. These details substantially help an agent understand side effects and recovery options.

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

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

The description is compact and front-loaded: purpose first, then operation semantics, then validation sequencing, then cost behavior. Every sentence contributes useful information without redundancy.

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

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

For a multi-operation mutation tool with no output schema, the description is fairly complete: it covers the core operations, key return values for save and delete, limits, and publication gating. Minor gaps remain around the list response shape and validate return value, but the agent has enough to invoke the tool correctly.

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

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

Schema coverage is already high at 75%, and the description adds operation-level meaning by explaining what each operation does, that deletion accepts up to 100 source campaign IDs, and that save returns ID, state, and version. It does not explain every parameter, but it meaningfully supplements the schema.

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

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

The description states a specific resource (unpublished workspace campaign drafts) and enumerates the supported operations: list, save, validate, and delete. It also distinguishes this tool from campaigns_publish_draft by noting that saving never publishes and validation is a prerequisite for publication.

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 clearly implied for each operation: list drafts, save/update a draft without publishing, validate before using campaigns_publish_draft, and delete unpublished drafts by source campaign ID. It does not comprehensively compare against other campaign-management siblings, but it provides strong operation-level guidance and names the key publication alternative.

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

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

Annotations already declare the mutation/destructive profile; the description adds genuinely useful context beyond them: the 500 KB size ceiling, that uploading is separate from launching ads, and that calls consume no Adrails credits. It stops short of covering retry/idempotency behavior for the upload path.

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, front-loaded sentences with no filler; the credit note is slightly tangential but still useful for agent budgeting. Structure lets the operation choice and the size escalation path be read first.

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 dual-mode tool with no output schema and a destructive hint, the definition covers the upload constraints but not what the list operation returns or what an upload actually creates in the account. Adequate but leaves an agent guessing about the read path.

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 75%, so structured fields carry most of the weight and a baseline 3 is appropriate. The description contributes the practical 500 KB limit that the raw base64 maxLength does not express semantically, but it says nothing about accountIds or idempotencyKey usage.

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

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

The description names both concrete operations (list platform media, upload a base64 image) and the resource, so an agent can tell what the tool does. It does not, however, differentiate this from media-adjacent siblings like google_ads_library or creative_insights.

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

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

It gives a clear guardrail — use the Adrails Campaigns uploader for larger images/videos — and clarifies that uploading does not launch ads. But it offers no guidance on when to pick 'list' versus sibling tools that also surface creative or platform assets.

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/non-destructive, yet the description still adds substantial context: available candidates are NOT confirmed selections, permission/event checks or a passed preflight; an unscoped call returns a picker and the agent must never choose for the person; empty asset lists indicate missing media or identity; never invent IDs or broaden scope. It also flags the absence of an embedded card and the need to surface a browser approval link.

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 content is valuable but crammed into one dense block that is not front-loaded: the tool's identity should lead, not a conditional use case. Some material is off-purpose for a read-only lister (the browser approval link for 'any proposed advertising change'), and the multiple negative instructions could be tightened into a short list.

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

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

With no output schema, the description carries the return-shape burden and does so thoroughly: it enumerates every field family returned, explains the picker fallback when no account is scoped, and interprets empty asset lists. An agent can predict both the success payload and the degenerate case before calling.

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

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

Schema description coverage is 75%, so the schema already documents platform, accountIds, userStatement and idempotencyKey; baseline is 3. The description adds some semantics ('Reuse the selected account and saved brief', 'passing userStatement verbatim', 'With no explicitly scoped account it returns a picker'), but idempotencyKey is unaddressed and account-scoping behavior is stated obliquely rather than as parameter 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 eventually names the concrete resource and returned fields (selected Meta accounts with accountId, currency, snapshot freshness, Page IDs, datasets, adSetDatasetIds, image hashes), and explicitly contrasts itself with campaigns_structure. However, it opens with a use case ('For a read-only launch-check...') rather than a verb+resource statement, so the core purpose arrives late and an agent must read several sentences to learn what the tool actually returns.

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

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

Explicitly states when to use it ('For building new ads, use this when account settings are needed'), when not to use it ('Not needed to change a budget, bid, status, placements, audience, dates or copy'), and names the correct alternative (campaigns_structure). It also routes open launch questions to launch_brief and instructs passing userStatement verbatim, leaving little 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real context beyond them: data is snapshotted 'from the last sync', null is returned for absent urlParameters, and MCP calls consume no credits. It omits pagination/result-size behaviour, keeping it at 4.

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

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

Purpose is front-loaded and every clause carries content about what is returned; there is no filler prose. It is dense and the Meta-specific tracking detail makes it long, but the length is justified by the breadth of the response shape it documents.

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 effectively serves as one, enumerating each entity and field an agent will receive. Combined with annotations covering safety and the 'last sync' freshness caveat, an agent has everything needed to call it and interpret results.

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

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

Schema coverage is 75%, just under the high-coverage baseline, and the description compensates by explaining that accountId scopes to one ad account and that campaignId 'narrows it to one campaign'. The remaining generic params (userStatement, idempotencyKey) are already documented in the schema, so no further detail 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?

Opens with a specific verb and resource: 'Reads, from the last sync, how an ad account's campaigns are built, on any platform,' then enumerates exactly what is returned (campaigns, ad groups/ad sets, keywords, asset groups, ads). This clearly separates it from write-oriented siblings such as campaigns_setup or campaign_drafts without needing to name them.

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?

States a clear when-to-use rule: 'Read it before building under an existing campaign or ad group, or before editing, and use only the ids it returns.' The optional campaignId narrowing is also explained. It stops short of naming an explicit alternative or exclusion, so 4 rather than 5.

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

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

Annotations declare destructiveHint=true, idempotentHint=false and openWorldHint=true; the description adds genuine value on top by bounding the destruction ('Delete returns an undo ID and never changes existing campaign drafts or published ads') and by stating that update replaces name/channel/payload while the type is immutable. It omits that mutations require an idempotencyKey and says nothing about permissions 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?

Five short sentences, front-loaded with the resource and scope, then operation-by-operation behavior, then a cost note. Each sentence carries information; it is dense but not padded.

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

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

For a four-operation mutation tool with no output schema, the description covers return shape for list (IDs, names, channels, types, payloads, timestamps) and delete (undoId), plus the immutability rule for update. The main gap is that the required idempotencyKey for mutations and the accountIds narrowing behavior are left entirely to the schema.

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

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

Schema coverage is 75%, so the schema already documents view, channel, templateId and payload. The description reinforces the important semantic constraints (type is fixed at creation, update overwrites name/channel/payload) but adds no detail about accountIds, idempotencyKey or payload structure beyond what the schema states.

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

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

The opening sentence names a specific verb and resource ('Manage reusable campaign, ad set or ad templates in the current workspace') and the description then enumerates all four operations (list/create/update/delete) with their scoping. It implicitly distinguishes itself from campaign_drafts and campaigns_setup by framing everything as reusable templates, though it never names those siblings.

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

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

Usage is implied through per-operation semantics ('Create requires a fixed type', 'update replaces... while retaining that type'), which helps an agent pick the right operation. But there is no explicit when-to-use/when-not-to-use guidance versus campaign_drafts or campaigns_setup, and no prerequisites for mutations.

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 the description adds meaningfully on top: paginated retrieval, 'No writes or saved learning', and the analytic caveat that rolling snapshots do not establish causal lift. It does not describe pagination mechanics or result volume limits, which is a minor gap.

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

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

Front-loaded and factually dense, but the opening 'Preferred after reading change-review' is awkward and presupposes context, and the trailing MCP/credits boilerplate ('use the input object for tool arguments', 'use no Adrails credits') does not help tool selection.

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, no-output-schema tool with a nested input object, it covers purpose, scoping constraints, pagination, mode selection, safety ('no writes') and the interpretive limit of the data. An agent can call it correctly without opening the schema.

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

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

Schema coverage is 75%, and the description reinforces the load-bearing semantics: accountId must be an exact selected account, actionId optionally narrows to one action, limit/offset paginate, and responseMode's two values are given distinct behavioural meanings. It adds value beyond the schema rather than restating it.

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

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

States a specific verb and resource: review recorded actions with application dates, baseline/observation eligibility, and outcome classification (pending/failed/skipped vs measured). It clearly separates this from a raw action list, though it never names a sibling (e.g. actions_recent) so the boundary 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?

Gives real routing guidance: 'Preferred after reading change-review', scope to an exact selected account and optionally one action, and a precise rule for responseMode=answer (diagnostic/outcome review, verification requests) vs evidence (explicitly requested extra deliverable, multi-account/multi-page collection). No explicit when-not-to-use or named alternative tool, keeping it below 5.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true, readOnlyHint=false, so the safety profile is covered; the description adds value the annotations cannot: targets are private and must never be repeated in answers, email channels save recipients without sending a test email, and calls consume no Adrails credits. It doesn't describe what deletion destroys or the resulting state, which keeps it below 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?

Purpose is front-loaded and every following sentence carries an operational constraint (creation scope, cross-channel operations, privacy rule, billing). It is dense but not padded; a slight restructuring separating capability limits from behavioral rules would have made it easier to scan.

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

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

For a multi-operation mutation tool with no output schema, the description covers creation limits, cross-operation availability, privacy handling, and cost. The remaining gaps are the required idempotencyKey for mutations and what a delete or test actually does, which the schema and annotations only partially imply.

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

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

Schema description coverage is 75%, so the schema does most of the work (kind enum, target vs webhookUrl alias, idempotencyKey). The description only indirectly contributes, mentioning email addresses as a target form, but says nothing about the operation discriminator, channelId, accountIds, or the required idempotencyKey for mutations. Baseline 3 is the right level.

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

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

The opening sentence names a specific resource ('automation delivery channels') and the full set of verbs (list, create, rename/update, test, delete). It is unmistakable against siblings like integrations_catalog or workflows_list, which cover different objects.

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 environment constraint: from this connection a channel can only be created or pointed at verified members' email addresses, while Slack/Discord/Telegram recipients must be added by a person in Adrails, and renaming/testing/deleting work for every channel. That clearly delimits what the agent can and cannot do here, though it doesn't point to an alternative tool or state prerequisites for the remaining operations.

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?

Despite read-only annotations, the description adds substantial behavioral context: history is scoped to this chat only, messages are not execution proof or permission, they must not set reply language, empty journals do not rule out outside changes, and live account data should be checked before decisions. These are exactly the caveats an agent needs before relying on recalled conversation data.

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

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

The description is front-loaded with the core scope and mode behavior, and most sentences carry operational value. It is dense and includes some platform-level meta guidance about MCP arguments and credits, which slightly dilutes conciseness but does not obscure the key instructions.

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 multi-mode recall tool with no output schema, the description covers scope, mode selection, pagination, and important interpretive caveats well. It does not fully describe the returned data shape, but it gives enough behavioral and usage context for an agent to call the tool correctly.

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

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

The description explains the key nested parameters that the schema leaves undocumented: mode behavior, query usage, beforePosition pagination, turnId plus part for single messages, and offset pagination for actions. It adds real meaning beyond the schema, though accountIds, userStatement, and idempotencyKey are left to their schema descriptions.

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

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

The description states a specific verb and resource: reading this chat's durable history, explicitly excluding other chats and workspaces. It distinguishes the three modes (messages, message, actions) so an agent can understand the tool's scope 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?

The description gives clear usage instructions per mode, including when to omit query, how to paginate, and how to broaden searches when no matches are found. It also warns not to treat historical messages as live or authoritative, but it does not explicitly name sibling alternatives such as actions_recent.

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, so the safety profile is covered. The description adds genuinely useful context: it costs no Adrails credits and returns structured content including metadata-gap diagnostics. However, it says nothing about data freshness, time window, or pagination behavior for the returned insights.

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

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

The core sentence is front-loaded with the grouping mechanism and the output list, followed by a clean usage sentence. The MCP/credits line is boilerplate but short and informative; nothing is padded or 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 no output schema, the description carries the return-value burden and does so by enumerating winners, fatigue, repeated usage, hook/hold rates, and metadata gaps. Annotations cover safety and the schema covers most params, leaving only minor gaps like the analysis window.

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 75%, so the schema largely documents accountIds, userStatement, and idempotencyKey itself. The description contributes nothing about limit, accountIds narrowing, or the nested input object beyond a harness boilerplate line, so it does not compensate for the remaining 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: "Groups Meta ads by the actual image or video asset," including the cross-ad/cross-account scope, which is a non-obvious capability. It then enumerates outputs (winners, fatigue, hook/hold rates, metadata gaps), so an agent knows exactly what it gets, though it never names a sibling it differs from.

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

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

"Use this before proposing creative variants or comparing hooks" gives concrete triggering conditions. There are no explicit exclusions or named alternatives (e.g., when to prefer creative_review or creative_market_evidence), 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 cover read-only, idempotent and non-destructive, so the description earns credit for adding things annotations cannot express: snapshot period/freshness caveats, the warning that results are not a country-level breakdown, and that visuals were not actually inspected. The one weakness is 'Selection and preview limits apply', which gestures at a cap without stating it (the schema's limit max of 30 implies it).

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

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

The tool-specific portion is dense and front-loaded, with the scope statement first, usage guidance second, and the caveat third. However, roughly a third of the text is generic MCP/transport and pricing boilerplate ('use the input object for tool arguments', 'free: MCP tool calls use no Adrails credits') that is not specific to selecting this 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?

This is a read-only tool with no output schema, so the description does not need to explain return values, and the freshness/scope caveats cover the main interpretive risk. The gap is the nested input object: an agent gets no description of what adIds, limit or nested accountIds do, nor what happens when adIds is empty, which for a 4-parameter tool with a nested object leaves 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 75% and only the top-level accountIds/userStatement/idempotencyKey carry descriptions; the nested input properties adIds, limit and accountIds are undocumented in the schema. The description's 'per-ad' phrasing hints that ad identifiers drive the call and 'preview limits' hints at the limit cap, but it does not clarify optionality or behavior when adIds is omitted. Baseline 3 is appropriate given the schema already handles most of the load.

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

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

The description names a concrete payload (per-ad performance, existing copy/media identifiers, parent ad set country targeting, snapshot period and freshness), which is far more specific than the title. It also explicitly states what the tool is NOT (a country delivery breakdown), which disambiguates it from a reporting-style sibling. It loses a point for not naming the nearest creative sibling (e.g. creative_insights) by name.

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

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

'Read before proposing reuse, localization or a new-market test' gives an explicit trigger condition, and the following sentence supplies a negative rule (do not attribute multi-country results to a single country, do not claim visuals were inspected). That is clear when-to-use plus when-not-to-conclude guidance. It does not name an alternative tool to use instead, so it stops short of a 5.

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

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

With readOnlyHint already provided by annotations, the description adds substantial behavioral context: no invented fatigue, winning status, product promises or sample thresholds. It also states that a source is a control candidate not a validated winner, that no asset is produced or campaign prepared, and that answer mode returns a report the agent writes from. This is rich beyond the structured annotations.

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

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

The description is dense but every sentence carries meaningful operational or safety constraints. It is front-loaded with the precondition and exclusions, though the paragraph could be easier to scan with clearer structure. It avoids redundancy and stays reasonably sized for a tool with this many behavioral rules.

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

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

The description is complete enough for a read-only review tool: it explains the evidence scope, what is included, what is not produced, and how answer vs evidence mode affects output. There is no output schema, but the description indicates that the answer mode returns a report the agent writes the reply from. Pagination behavior and language semantics remain delegated to the schema and are minor 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?

The description fully explains the focus modes (copy_test, market_transfer) and gives strong guidance on responseMode evidence vs answer. Schema description coverage is 75%, and the schema documents adIds and destination well. Language, limit/offset and accountIds are not elaborated in the description, so it is not 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 states a specific verb and resource: review exact selected ad evidence after certain prior analyses. It also clearly excludes creation ('No asset produced or campaign prepared') and invented conclusions. It does not explicitly distinguish itself from close siblings such as creative_insights or creative_market_evidence, which keeps it at 4 rather than 5.

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

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

It specifies when to use the tool: after creative-map, creative-fatigue, creative-roadmap or market-test. It also explains when to use each focus mode and when to choose evidence vs answer. It does not explicitly say when to prefer sibling tools instead, but the internal mode guidance is clear.

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

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

Goes well beyond the readOnly/openWorld annotations: states it uploads and launches nothing, scopes access to folders shared with the workspace's Google address, explains the empty-result meaning (not shared yet), and notes there is no embedded card and approvals go through the browser link.

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

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

Front-loaded with the core read action and the folderId branch before the search fallback. Dense and somewhat run-on, with politeness/UI instructions (browser approval link) that could be trimmed, but nearly every sentence carries behavioral information.

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

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

With no output schema, the description fully specifies the return shape (path, measured ratio, pixel size, duration, file size, default ad grouping, three-level depth) plus failure modes and follow-up routing — everything needed to call and interpret it.

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?

Adds real meaning for folderId (provenance: a type=drive_folder mention or a search result) and query (name-contains match, most recently changed first), which the bare schema lacks. adPerFile and accountIds carry their semantics mostly in the schema, so not a full 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?

Specific verb and resource: reads the creatives in a Google Drive folder, and states two distinct modes (list by folderId vs search by query). Clearly distinguishable from siblings like creative_review or campaign_media.

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

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

Explicitly defines when folderId is present vs absent and what each branch does; also instructs what to do when the default grouping doesn't fit (say how you'd group and ask the deciding question) and routes launch questions to launch_brief.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the bar is lower and 'Read only' merely restates them. Beyond that, the description adds genuinely new operational context: calls consume no Adrails credits and results (reports/questions) come back as structured content rather than prose.

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

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

The first sentence front-loads purpose, scope and the read-before-use instruction with no filler. The trailing MCP/credit sentence is generic boilerplate that is not specific to this tool, which costs it a point but does not bury the essential information.

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

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

There is no output schema, and the description compensates by saying the result is a full enumeration of settings each with allowed values and format, so an agent knows what comes back. The main omission is guidance on the no-argument invocation shape and on how a large result set is returned.

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

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

Schema description coverage is 75% and the three named parameters (accountIds, userStatement, idempotencyKey) are documented in the schema itself, so the baseline applies. The description says nothing about the required empty 'input' object, which is the only genuinely ambiguous part of the schema; noting 'takes no arguments' would have been the value-add.

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 ('Returns every setting of the Meta campaign editor') plus the exact scope ('that launch_brief's metaSettings accepts') and the payload each entry carries (allowed values and format). An agent can distinguish this reference lookup from launch_brief and targeting_options 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?

'Read it before passing metaSettings' gives an explicit ordering trigger tied to a named sibling tool, which is clear usage context. It stops short of stating when the reference is not needed (e.g. if metaSettings is unused) or what to do if a requested setting is absent.

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

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

Annotations already declare this a safe, idempotent read, so the bar is lower; the description nonetheless adds substantial interpretive context — the finding taxonomy (confirmed issue, policy deviation, hypothesis, platform context, not applicable, unknown), evidence/snapshot date/currency/owner fields, and explicit caveats that severity is not causality and that placements, missing tags, or CPM/CTR do not establish wasted spend or fatigue. It omits practical behavior such as how limit/pagination works or how findings are ordered.

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, but the paragraph is overloaded: a long taxonomy list, multiple interpretive caveats, and boilerplate about input objects, structured content, and credit costs that does not help an agent select or invoke the tool. Several sentences could be trimmed without loss.

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

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

With no output schema, the description compensates by enumerating what each finding contains and how to interpret classifications and caveats, which is what an agent needs to use results correctly. It falls short only on filtering/paging behavior for a 4-parameter tool.

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

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

Schema description coverage is 75%, so the schema already carries most parameter documentation. The description mentions only implicitly scoped 'selected campaigns' and adds nothing about limit, family, minSeverity, or accountIds semantics, so the baseline applies.

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

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

The first sentence names a specific action and resource: a contextual review of rule-engine findings on selected Meta and Google Ads campaigns, judged against the workspace's own standard. It also distinguishes itself from reporting_overview, though the phrasing is dense and the second half drifts into output description rather than purpose.

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

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

It names an explicit alternative and the condition that selects it ('Use reporting_overview for the whole portfolio, including campaigns without findings') and adds procedural advice about comparing compatible groups before synthesizing priorities. It does not position itself against other review/diagnostic siblings (creative_review, performance_diagnose, business_review), leaving some routing ambiguity.

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 is covered. The description adds the usage policy that only listed or user-supplied pictures may be used, which is genuinely useful, but nothing about scope limits, freshness of the library, or per-account behavior. The trailing MCP/credits boilerplate is generic and not tool-specific.

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 sentence is front-loaded and followed immediately by the practical use cases and the usage constraint; no wasted phrasing in that core. The trailing 'MCP: use the input object... Free: MCP tool calls use no Adrails credits' is generic boilerplate that dilutes focus slightly.

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

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

There is no output schema, and the description compensates by naming the fields returned for both pictures and audiences, which is exactly what an agent needs. Combined with the usage constraint and downstream reuse guidance, it is nearly complete for a read-only library lookup; only pagination/size limits are 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 75%, with accountIds, userStatement and idempotencyKey documented in the schema itself. The description says nothing about the required accountId or the nested input wrapper, so it adds no meaning beyond what the schema provides — baseline 3 applies.

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

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

States a specific verb and resource ('Reads a Google Ads account's picture library ... and its audiences') and enumerates the returned fields (assetId, address, size; id, name), so an agent knows exactly what data comes back. It is clearly distinguishable from siblings like campaign_media or targeting_options, which do not read account asset libraries.

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 when-to-use guidance: reuse pictures by assetId in google_ads_build and name an audience signal for a Performance Max asset group. It also states a hard constraint ('Only the pictures listed here or given by the person may be used'), but does not name an alternative tool or say when not to call it.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds meaningful context beyond that: counts are scoped to the given countries/language or worldwide by default, results are returned as structured content, and calls consume no Adrails credits — useful for an agent deciding whether to spend a call. It omits result-size limits and pagination behavior.

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

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

The core is front-loaded and mode-driven in two dense clauses with no wasted phrasing. The trailing MCP boilerplate and the 'Free: ... no Adrails credits' line are somewhat mechanical, but the latter carries real decision value, so the text remains efficient overall.

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 must convey what comes back, and it does: for each mode it states the returned figures and ordering ('most searched first'). Combined with the declared scoping defaults and the read-only guarantee, an agent has enough to call this correctly.

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

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

Schema coverage is 75% and the description still adds real meaning: 'mode' semantics are explained per value, 'url' is tied to the ideas mode as an https page of the site, and countries/language are described as falling back to 'everywhere' when omitted — a default the schema doesn't state. It doesn't cover the keyword array limits (200 items, 80 chars), but those are documented in the schema itself.

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 ('Reads Google's Keyword Planner for a Google Ads account') and then defines both operating modes with what each returns: monthly search volume plus top-of-page bid range for 'volumes', and keyword suggestions from seed words or a page URL for 'ideas'. This is far more specific than any sibling ('google_ads_library', 'targeting_options') and lets an agent know exactly which tool produces real search-volume data.

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

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

It gives a clear use case ('choose a search campaign's keywords on real searches rather than guesses') and implicitly tells the agent which mode to pick based on whether it has seed keywords or a URL. It stops short of naming an alternative sibling tool or stating when not to use it, so it falls just below the explicit when/when-not/alternative bar.

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

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

Annotations already establish readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds useful non-annotation context: MCP tool calls use no Adrails credits, which matters for agent planning. It does not discuss pagination or result ordering, but for a read-only catalog that is a minor gap.

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

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

Two short sentences, front-loaded with the core purpose followed by a relevant billing note. There is no filler and nothing wasted.

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

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

For a read-only catalog tool with annotations covering safety and no output schema, the description gives enough conceptual output scope: providers, data, and connection requirements. The remaining gaps are sibling differentiation and any note about the unusual required 'input' parameter, both of which are minor given the 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 75%, so the schema already documents most parameters, and the description adds no parameter-specific information. The presence of an odd required nested 'input' object and shared-looking fields like userStatement and idempotencyKey is not clarified, leaving the agent to rely entirely on schema descriptions.

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

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

The description uses a specific verb (List) and clearly names the resources returned: implemented providers, available data, and connection requirements. It is distinguishable in broad terms from sibling tools like integrations_detail and integrations_status, though it does not explicitly contrast itself with them.

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 'List' — this is the discovery/catalog tool — but the description gives no explicit when-to-use guidance or alternatives. It does not tell the agent when to call this instead of integrations_detail or integrations_status.

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 elsewhere. The description adds one genuinely non-obvious trait — that calls consume no Adrails credits — but says nothing about auth/scope requirements or pagination/limits on the returned stream data.

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

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

Two compact sentences with zero waste: the operation and its return contents come first, and the credit-cost note is appended as a secondary fact. Every clause earns its place.

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

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

With no output schema, the description does sketch the return contents, which is the right instinct. But for a nested-object tool where connectionId is required, it never says where to obtain a connectionId (presumably integrations_status/catalog), leaving a real gap for an agent trying to call it correctly.

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

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

Schema description coverage is 75%, so the schema largely documents accountIds, userStatement, and idempotencyKey itself. The description adds no meaning about connectionId (the one required param) or how accountIds narrow scope, so it neither compensates for nor extends the schema. Baseline 3.

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

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

States a specific verb ('Read') and resource ('one connection') plus the contents returned: imported data coverage, sync streams, and trend. It is distinguishable from list-oriented siblings like integrations_catalog and integrations_status by the 'one connection' scoping, though it never names them.

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 'one connection's' implies this is the single-record drill-down, but there is no explicit when-to-use/when-not guidance and no mention of the sibling tools (integrations_status, integrations_catalog) that an agent would otherwise pick. Usage must be inferred from context.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new behavior: calls cost no Adrails credits, and UI reports/questions come back as structured content. It does not describe response shape or how freshness is expressed, which keeps it below 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 capability statement and the "read this before" guidance are front-loaded and earn their place, and the concrete example answers are useful. However, the trailing block is boilerplate, and "MCP: use the input object for tool arguments" is actively confusing given the required input object has no properties.

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

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

With no output schema, the description carries the burden of explaining return values; it gestures at them (per-source capabilities, per-stream freshness) but never states the shape. Sibling differentiation against integrations_catalog and integrations_detail is also absent. It is enough to know when to call it, but not enough to predict what comes back.

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

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

Schema description coverage is 75%, so the schema already documents accountIds, userStatement and idempotencyKey. The description says nothing about any parameter, leaving the required but property-less "input" object unexplained and offering no hint that accountIds can only narrow access. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific resource and its facets: what is connected, what each source can do, and per-stream freshness. That is more than a restatement of the name. It does not distinguish itself from the sibling tools integrations_catalog and integrations_detail, so an agent cannot tell from the description alone which of the three to open.

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 trigger — "Read this before saying a figure is missing" — and illustrates the shape of a good answer ("connect Shopify", "the order sync has been failing since Tuesday"). It stops short of naming alternatives or when-not-to-use, notably the integrations_catalog and integrations_detail siblings, so it falls short of a 5.

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

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

Annotations already cover read-only, idempotent and non-destructive behavior, and the description adds genuinely new context: state values are distinct and completion must not be inferred, plus a cost note that calls consume no credits. It does not cover behavior for missing/expired jobs, but the added semantics exceed the annotation baseline.

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

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

Front-loaded with the core purpose in the first sentence, followed by the state-semantics caveat and the cost note. Three compact sentences with little waste, though the credits note is tangential to invocation correctness.

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

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

For a read-only tool with no output schema and a nested input object, the description covers the interpretive risk (state distinctions) but leaves how to identify a job (id vs key vs tool) and what happens for unknown/expired jobs unexplained. Adequate but with clear gaps.

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

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

Schema coverage is 75%, so the schema largely documents id, key, kind and tool; the description adds only a partial mapping by naming four of the five kinds (omitting "operation"). It gives no hint on how id vs key vs tool select a job, so it does not add meaning beyond the structured fields.

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

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

States a specific verb ("Read") and specific resource ("persisted background job, publication, action or workflow state"), which cleanly distinguishes it from sibling list/action tools like workflows_list and actions_recent. It stops short of explicitly naming a sibling or contrast case, so it is clear but not maximally differentiated.

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

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

"Do not infer completion" gives real interpretive guidance about how to use the returned state, which is more than nothing. However, there is no explicit when-to-use/when-not guidance versus alternatives (e.g., workflows_list, actions_recent, workflows_preview), leaving the agent to infer routing.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and idempotentHint=true, so the bar is lower; the description usefully confirms 'saves nothing' and names the two possible returns (a shortcut payload to save, or a link where an instruction is added). It does not explain what happens on a rejected/duplicate instruction, or why a mutation-grade idempotency key appears in a read-only tool.

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

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

Three short sentences, front-loaded with the core behavior and the no-save guarantee; the credits note is a slight tangent but short and decision-relevant. No wasted clauses.

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

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

With no output schema, the description carries the return-value burden and does so by naming both outcomes. For a nested-input tool with 75% schema coverage this is close to sufficient; what's missing is failure behavior when the statement conflicts with existing Knowledge entries.

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 75%, so baseline is 3. The description does add real meaning to the `kind` enum by glossing 'durable instruction' versus 'reusable request (shortcut)', but says nothing about `command`, `accountIds`, or `userStatement`, which carry the remaining ambiguity.

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

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

States a specific verb and resource: it checks a person's stated instruction or shortcut against what Knowledge already holds, and explicitly clarifies that it is a validation step, not a save. That distinguishes it from knowledge_manage (named as the save path) and from knowledge_skills, though the sibling it names is not in the provided sibling list.

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

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

Clear sequencing guidance: call this first, then only after the person says yes use knowledge_manage to persist. It also gives a cost reason to prefer it (free, no Adrails credits). It does not state when NOT to use it (e.g. when the instruction is already saved, or when no user has confirmed).

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 safety is covered. The description adds real context beyond them: lists return metadata only with a `nextOffset` cursor, reads return the full method body in a single call, and scope/approvals constraints still apply. It stops short of describing what the body or metadata contain or what happens on an unknown key, which is why this is a 4 rather than a 5.

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

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

Front-loaded with the action and the preferred path, and each sentence carries operational content (route keys, pagination, mandatory method use). The closing MCP boilerplate about the input object and structured content is generic padding, and the credit-cost note is useful but sits after the payload rather than near the top.

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, no-output-schema tool with a nested input object, the definition covers modes, pagination, scoping, and approval caveats — enough to invoke it correctly. The main residual gap is that return shape (what metadata vs. full body look like) is only hinted at, which matters given there is no output schema to fall back on.

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

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

Schema coverage is 75% and the schema already documents `offset` and `command`, but not `query` or `skillId`. The description fills that gap by explaining the query→skillId handoff and clarifying that `command` is an exact installed method key scoped to the current source. It does not cover the nested `accountIds`/`userStatement`/`idempotencyKey` fields at all, leaving that gap to the schema.

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

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

Opens with a specific verb+resource+timing: 'Choose and read a workspace method before specialist work.' It then names the two concrete modes (command key read vs. query search then skillId read) and gives example route keys (budget-pacing, unit-economics, revenue-reconciliation), so an agent knows exactly what this returns versus any other tool in the list. No sibling overlaps on method retrieval, so sibling differentiation is effectively satisfied.

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 rule: prefer `command` when the route key is known to load the body in one call, otherwise search with `query` and read a returned `skillId`. It also pre-empts a likely wrong inference by stating that strategic proposals, read-only plans, and 'do not launch' requests STILL REQUIRE their method — that is a when-not-to-skip rule, not just a when-to-use one.

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

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

Annotations declare destructiveHint=true and openWorldHint=true; the description earns credit by defusing that ('Nothing goes live or spends without browser approval') and by disclosing the credit cost and the fact that UI cards are returned as structured content rather than rendered. It stops short of saying what the call itself persists or that retries must reuse an idempotency key, 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?

Sentences are short, imperative and front-loaded: purpose, then input rule, then the ask/answer loop, then the guardrail, then the approval outcome. Only the trailing MCP/credits note and the repeated confirmation framing are slightly 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 large multi-field brief builder with no output schema, it covers the interaction loop, the prohibition on inventing account/budget/mode values, and the approval gate before spend. What it omits is the retry/idempotency contract and a clearer statement of what is saved between calls – both relevant given the destructive and non-idempotent 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 coverage is 75% and nested, so the baseline is already high; the description still adds real meaning by stating the rule for the unlabeled 'input' object (only confirmed choices, never guesses), the verbatim userStatement requirement, and 'map names only to supplied IDs'. That is a semantic constraint the schema alone does not encode.

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

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

States a specific verb and resource ('Prepare or continue a Meta launch brief') and immediately scopes it to force-collecting a userStatement plus only confirmed input choices. An agent can tell this apart from campaign_drafts, campaigns_setup or editor_settings_reference 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?

Explicit ordering rules ('Call before asking questions, then ask the returned open questions ... and call again with the answers') plus hard exclusions ('Never choose an account, budget or launch mode for the user'). It even names the downstream handoff (campaigns_launch) and the free-text fallback, 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 cover safety (readOnly, idempotent, non-destructive), but the description adds real value: determinism, the full enumeration of returned fields despite no output schema, the input domain constraints, and a cost note that calls consume no credits. The trailing 'MCP: use the input object...' boilerplate is generic and not tool-specific, which keeps it just short of 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 first three sentences are front-loaded and each earns its place: purpose, usage gate, and returns. The appended MCP/credits boilerplate is workspace-standard filler that dilutes an otherwise tight definition.

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

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

For a simple read-only two-number comparison with no output schema, the description covers purpose, gating, return fields, and input domain. The only real gap is unit/scale expectations and what happens with edge cases like a zero-ish observed value, which an agent may need to reason about.

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 75%, so the baseline is 3. The description does add domain meaning to the two undocumented nested fields by stating observed must be non-negative and target positive, but it says nothing about accountIds scoping or whether both values must share units — the more consequential semantic question for a ratio computation.

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 — deterministically compares an observed metric against a target — and pins the exact output semantics (signed difference, relative difference percent, attainment percent, above/below/equal). It is clearly distinguishable from sibling metric tools like metrics_daily or performance_period, which report values rather than a single computed comparison.

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 gate: use ONLY when the person explicitly asks for the numeric difference, percentage gap, or attainment percentage, and explicitly says a normal performance-vs-target answer should just state both values without this call. It also names an exclusion ('not for causal claims or trends'), leaving almost 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 readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds non-obvious behavioral context: the screen auto-draws day-by-day detail for three metrics or fewer (so no verbal request needed) and draws a ranking for breakdowns, plus a hard scope exclusion for Meta. It stops short of describing response shape or pagination/limits, keeping it at 4.

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

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

Front-loaded with the resource definition, then progressively adds usage rules, UI behavior, and the exclusion. The triple-clause metric enumeration is long but each clause carries distinct information; no obvious filler sentences.

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

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

No output schema exists, so the description must carry return-value burden; it does so partly by describing what the screen renders (daily series, ranking) and what is excluded. An agent still cannot fully predict the payload structure for breakdowns or empty periods, a minor but real gap.

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

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

Schema coverage is 75% with date bounds documented and `metrics`/`breakdown` typed but not described. The description compensates by explaining that omitting `metrics` returns everything (discovery pattern) and what `breakdown` splits by (product, traffic source, country), which is real added meaning. However, it omits the 12-metric cap implied by maxItems and gives no guidance on valid breakdown values, so it only partially fills the 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 opening clause names a specific resource (daily series) and enumerates what it measures per integration domain (traffic/sessions/conversion/sales/AOV, email metrics, profit/CPA/ROAS). It explicitly carves out Meta campaign data and points to reporting_overview, so an agent can separate it from siblings 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 concrete calling conditions: call without `metrics` to discover available names, use `breakdown` to split instead of totals, and use reporting_overview for Meta campaigns. These are explicit when-to-use and when-not-to-use statements with a named alternative.

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

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

Annotations already cover read-only/idempotent/no-writes, yet the description still adds substantive behaviour: 'no writes', 'missing rows are never zero', 'generic results never purchases', the date-fabrication prohibition, and the fact calls consume no credits. These are genuine caveats an agent could not derive from the annotation block.

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

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

Front-loaded with the core comparison statement, but the opening "Preferred after reading performance-diagnosis" is cryptic, 'separates facts, unknowns and next verification' is under-explained, and the MCP/credit boilerplate at the tail dilutes the operational content.

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 nested four-parameter diagnostic with no output schema, the description covers the snapshot scope, date discipline, responseMode contract and modelling caveats. Minor gaps remain on what the 'verified report' actually contains and how the two periods' lengths are validated.

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 75%, so the schema largely documents accountId, before/after and actionType itself. The description reinforces responseMode's answer/evidence distinction and the 'never infer the event from a campaign title' rule, but adds little beyond what the enum descriptions already say.

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 (compares) over a specific resource (two equal-length, non-overlapping periods from one saved Meta snapshot) and enumerates outputs (coverage, changes, facts vs unknowns). It does not name sibling tools like metric_compare or performance_period, so the agent must infer differentiation, but the core purpose is unambiguous.

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

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

"Preferred after reading performance-diagnosis" and "Requires exact account ID and dates from the request/context; do not invent dates" give some use-context and a hard constraint, and responseMode's answer-vs-evidence rule is spelled out. There is no explicit when-not or routing to the neighbouring comparison/reporting tools, leaving real ambiguity about when this beats metric_compare or performance_period.

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, so the safety profile is covered. The description still contributes real operational context beyond that: the 400-day cap, the account-time-zone date semantics, and the caveat that additive metric sets may not return reach and frequency. It does not describe pagination or how multiple accounts/entities appear in the response, so it sits mid-range rather than at the top.

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

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

Dense but front-loaded: the verb, scope and date constraint come first, followed by metric-set routing. Every sentence carries information except the trailing credits/'free' note and the MCP input-object reminder, which are boilerplate rather than tool semantics.

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

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

No output schema exists, so the description must carry the return semantics, and it does: it enumerates the metric classes returned and states that comparisons yield each entity's change. Combined with level, date-range and filter semantics, an agent has everything needed to call it correctly.

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

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

Adds meaning well past the 75% schema coverage: dates are YYYY-MM-DD in the account's time zone, campaignIds narrows the read while entityIds only filters returned rows, and metricSet is given a decision rule rather than just an enum label. compareSince/compareUntil are explained as producing per-entity change. Minor gap: no guidance on whether compare pair must be equal-length or within the 400-day window.

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

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

States a concrete verb and resource ('Reads one ad account's provider figures for an exact date range'), names both supported platforms, all four levels, and enumerates the returned metrics. It also anchors itself against the alternative ('any question about a period other than the synced window'), which separates it from metrics_daily-style siblings.

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

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

Explicit selection rules: use it for periods outside the synced window, trends, or before/after; use compareSince/compareUntil for a second range; choose metricSet=additive for spend/conversion/efficiency and standard for reach/frequency/fatigue. The agent has a decision procedure with no inference required.

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, and the description adds real value beyond them: it returns arithmetic plus limitations and explicitly is not a forecast, verified profitability, optimized allocation or spending approval, and it neither reads accounts nor modifies anything. The credit-cost note is a useful extra, though nothing is said about output shape in detail.

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?

Core capabilities and constraints are front-loaded in the first two sentences, and the guardrails are stated tersely. The trailing MCP/credits sentence is operational rather than semantic and slightly dilutes an otherwise tight definition.

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

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

For a nested three-variant calculation tool with no output schema, the description establishes what comes back (arithmetic plus limitations), the input discipline, and the safety posture. Full completeness would require distinguishing the three calculation types and their distinct inputs.

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 75% and the description reinforces the semantics of the key inputs: one currency with no conversion, evidence must carry sources and exact periods, and missing values must not be guessed. The three calculation subtypes are named but not explained in terms of their required fields, so it stops short of 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 first sentence gives a specific verb-plus-resource ('Deterministic budget pacing, budget allocation totals, or first-order acquisition unit economics') that clearly delimits the tool to arithmetic rather than recommendation. It does not name a sibling alternative, so the agent must infer the contrast with budget_recommend.

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 rules: use verified inputs or clearly labelled hypotheticals, cite sources and exact periods in evidence, use one currency, never guess missing budgets/costs/time windows. It lacks an explicit 'use X instead when...' routing to siblings such as budget_recommend, keeping it at 4.

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 safety (readOnlyHint, destructiveHint=false, idempotent), and the description still adds real value: pagination, that campaigns with no findings are included, the cap of three priorities, and an explicit negative list of what it will not fabricate (CPA, causal defects, pause duration, QA purpose, budget/test plan). That negative scope is unusually useful for calibrating trust in the output, though it does not describe the report's actual shape or page-size behavior.

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

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

The opening sentence is a long run-on that packs scope, inputs and constraints together, making the core purpose slower to extract than it should be. The trailing MCP/UI/credits block is meta-guidance rather than tool semantics and dilutes the front-loaded content, though the 'no writes' and responseMode guidance is placed usefully.

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 still tells the agent what to expect: a paginated report written from responseMode=answer, plus the three-priority cap and inclusion of empty campaigns. Given a nested input object and four parameters, that is close to sufficient; only the report's internal structure remains unspecified.

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

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

Schema description coverage is 75%, so the schema already carries language, accountIds, responseMode and pagination semantics. The description reinforces responseMode with a use-case example (creative brief, executable plan) and notes 'Paginated', but adds nothing about limit/offset defaults or ceilings that the schema does not already state. Baseline 3 is appropriate where structured fields do the heavy lifting.

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

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

The description names a specific activity (advise across selected accounts and campaigns, synthesizing at most three portfolio priorities) and grounds it in concrete inputs: each campaign's objective, ad-set events, budget ownership and freshly evaluated rules. It is clearly a cross-account advisory report rather than a single-account diagnostic. It stops short of naming which sibling (business_review, performance_diagnose, findings_review) it supersedes, 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?

Sequencing is explicit ('After audit'), and the responseMode choice is spelled out: leave as answer for a diagnostic/outcome review, use evidence only for an explicitly requested extra deliverable or multi-account/multi-page collection. No guidance is given on when to prefer this over business_review or performance_diagnose, which are the nearest siblings.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real behavioral detail on top: the 93-day cap, explicit gap reporting with complete=false when coverage is missing, that exact ad-set/ad periods are unavailable on Meta, and that Meta figures may be visits/leads/clicks rather than purchases. Minor gap: it doesn't describe shapes of returned rows beyond the coverage flag, though it does hint at requestedPeriod.

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 and nearly every clause carries operational information, but the body is a dense run-on chaining conditionals across several sentences. The trailing boilerplate about the input object, UI reports, and free credits is generic and dilutes the core guidance.

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

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

No output schema exists, and the description compensates by stating what a dateless read returns (latest synchronized window with entity settings and status), what coverage gaps look like, and how comparison rows come back. For a nested-input, multi-mode reporting tool, an agent has enough to call it correctly.

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

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

Schema coverage is 75%, and the description closes the remaining gap: lastDays is N complete calendar days excluding today on a UTC reference with server-resolved inclusive bounds; entityIds switches the whole read to exact entities with a 7-vs-7 comparison for campaigns; compare adds a prior-period row with percent change. That is meaning well beyond the schema's field-level text.

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

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

The opening sentence names the exact resources returned (spend, attributed revenue, named conversion events) and the scope (the workspace's connected Meta and Google Ads accounts). It explicitly routes ad-group/ad-over-dates and Google exact-period reads to performance_period, so an agent can separate it from that sibling without opening either schema.

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

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

Gives explicit selection rules: lastDays vs. from/to (both required together), compare=true instead of a separate prior-period read, performance_period for Google exact periods, store_revenue for store orders, and 'never compare rolling-window totals as independent periods.' Exclusions and alternatives are named, not implied.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world, so safety is covered; the description adds real behavioral context beyond that: each source and currency is kept explicit, attribution is not inferred without an identity join, cadence counts appear only when customer-level subscription data exists, and RevenueCat ARR is derived as normalized MRR x 12. These are meaningful disclosure about result semantics and limitations. It does not discuss limits, pagination, or partial-source failure behavior.

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

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

The metric inventory is front-loaded and each later sentence (cadence counts, ARR derivation, no-inference rule) adds distinct information. The trailing MCP invocation note and free-credit sentence are boilerplate that does not help tool selection and dilutes the body slightly.

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 must characterize the payload, and it does: named metric families, cadence breakdowns, and the guarantee that sources and currencies stay separate. For a read-only aggregation over three systems this is largely sufficient, though result shape (structure per source/currency) and behavior when one source is unconnected are left implicit.

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

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

Schema coverage is 75%, so the schema largely documents from/to, accountIds, userStatement and idempotencyKey itself. The description adds nothing about the date-window semantics, account scoping, or how idempotencyKey relates to what is described as a read-only tool. Baseline 3 applies when the schema carries the parameter burden.

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 exact data sources (Stripe, RevenueCat, PostHog) and enumerates the metrics returned: active subscriptions, trials, normalized MRR, ARR, collected payments, refunds, daily product events, plus customer/subscription counts by billing cadence. That is far more specific than the title 'Saas performance'. It does not, however, explicitly contrast itself with adjacent siblings such as store_revenue, metrics_daily or performance_period.

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 usage directive with an example question ('how many customers pay annually or monthly'), which tells an agent the intended question class. It offers no exclusions or named alternatives, so the agent must infer routing against the many sibling 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 declare readOnly, idempotent, openWorld and non-destructive, yet the description still adds real value: no account/upload/launch side effects, no credit cost ('MCP tool calls use no Adrails credits'), and the absence of an embedded card with the note to surface a browser approval link. It stops short of failure modes or fetch limits, keeping it at 4.

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

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

Purpose and return payload are front-loaded, and nearly every clause carries actionable detail. It is dense and slightly over-packed with semicolon-chained clauses, and 'Read only' partly restates the readOnlyHint annotation.

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

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

With no output schema, the description does the heavy lifting by enumerating the returned fields and the launch_brief values it settles. Only minor gaps remain — how failures or non-Shopify sites are handled — which an agent can tolerate given the read-only annotations.

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

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

Schema coverage is 75%, so the schema already documents url, accountIds, userStatement and idempotencyKey. The description reinforces url implicitly and adds useful context on userStatement (verbatim, required for launch_brief), but says nothing about accountIds scoping or idempotencyKey — baseline 3 is appropriate.

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

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

States a specific verb and resource ('Reads a public website or store') and enumerates exactly what it returns: brand, product list, language, currency, prices, links. It is clearly distinguishable from sibling store_products, which covers connected-store data rather than a public page scrape, and it names the downstream consumer (launch_brief).

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

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

Gives an explicit trigger ('when its contents are needed for the requested ads') and explicit exclusions: it 'does not infer the account, budget, countries, dates, Page or pixel; reuse those from the request and saved brief.' It also routes the agent elsewhere for open questions via launch_brief with userStatement passed verbatim.

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 and open-world, but the description adds two things they do not: full email addresses are deliberately not stored, and offset is the paging mechanism when the total exceeds limit. The no-invented-email instruction is a valuable guardrail; data freshness of imported records is still unstated.

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

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

The field list, trigger condition, email caveat and paging note are front-loaded and earn their place. However the trailing boilerplate about MCP argument passing, structured content and free credits is generic platform text, not tool-specific, and dilutes the definition.

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

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

With no output schema, the description compensates by enumerating the returned fields and ordering, and it explains pagination. For a read-only list tool the remaining gap is minor: how fresh the imported commerce data is and whether search is substring or prefix.

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 75%, so the schema carries most of the burden. The description meaningfully explains offset/limit paging, but the `search` parameter is never mentioned, so one of the three input fields has no semantics anywhere in the definition.

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

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

States a specific resource (customers imported from a Stripe/commerce connection) and enumerates the exact fields returned, plus the sort order (newest first). An agent can distinguish it from store_orders, store_products and store_revenue 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 trigger: "Use this when the person asks for clients or customers," which maps colloquial phrasing to this tool. It stops short of naming the sibling to use for orders, products or revenue reporting, so routing among the store_* family is only implied.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, non-destructive), so the description's job is to add operational detail, and it does: explicit ordering (most recent first), unit of return (one row per order), the implied 50-row ceiling, and the fact that calls consume no credits. It omits whether results paginate or how to reach orders beyond the cap.

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

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

The core content is two tight, front-loaded sentences that lead with the returned data shape and then route to the alternative. The appended MCP transport and free-credit sentences are boilerplate but short and do not bury the main point.

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

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

With no output schema, the description carries the burden of describing returns, and it does list the key columns, which is helpful. But it leaves out pagination behavior for the 50-row maximum and the exact effect of a status filter on result ordering — gaps an agent would hit on the first call against a large date range.

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

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

Schema description coverage is 75%, so the schema largely documents from/to, limit and accountIds itself. The description only adds the practical implication of the 50 cap ('instead of fifty') and the status filter by mentioning financial status; accountIds, userStatement and idempotencyKey receive no coverage in prose.

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 resource and granularity: order-level rows, most recent first, with totals, financial status, fulfilment status and line count. It distinguishes itself from store_revenue by contrasting per-order listing with period aggregation. The verb phrase 'Orders one by one' is slightly awkward but the intent 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?

It names a concrete alternative and the condition selecting it ('For a total over a period, store_revenue costs one call instead of fifty'), which is exactly the routing an agent needs. However, 'For looking at a specific order' is misleading because no order identifier parameter exists, and it does not mention when to prefer store_customers or store_products.

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, open-world behavior, so the safety profile is covered. The description adds genuinely new traits: the sort order (title), the 50-item cap, the returned field list, and the explicit no-credit cost note. It does not mention pagination or whether a result cursor exists, but that is a modest gap given the annotation coverage.

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

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

The core paragraph is dense, front-loaded, and every clause carries information. The trailing boilerplate about using the input object, structured UI content, and free credits is generic and not specific to this tool, slightly diluting focus.

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

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

With no output schema, the description usefully enumerates return fields and the title sort, and it explains both filters, which covers what the agent needs to call it. It stops short of noting result truncation behavior when more than 50 products exist or any account-scoping nuance, but the essentials are present.

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

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

Schema coverage is 75% and the schema already spells out limit, search (case-insensitive substring), and status (exact match). The description largely repeats those semantics rather than adding format examples or edge cases, and says nothing about accountIds, userStatement, or idempotencyKey beyond what the schema documents. Baseline 3 is appropriate.

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

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

States a concrete verb and resource with scope ('Browse up to 50 products from connected commerce stores, sorted by title') and enumerates the returned fields. It also names the two adjacent siblings it is not, so an agent can distinguish catalogue browsing from order and revenue tools without opening a schema.

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

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

Explicitly routes usage: 'Use this for catalogue lookup, store_orders for individual transactions, and store_revenue for aggregated sales.' It further clarifies which filter to use for title matching versus exact status, leaving little 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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds non-obvious behaviour: figures are returned per store in that store's own currency and never converted, the sales components are kept separate rather than netted, and calls consume no Adrails credits. It does not cover pagination or a date-range 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?

The first sentence is dense and front-loaded with the useful content. The trailing block ('use the input object for tool arguments', 'UI reports and questions are returned as structured content') is generic wrapper text that does not help an agent select or invoke this specific tool, though the free-credit note carries some value.

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 reporting tool with a documented schema and no output schema, the description covers scope, currency behaviour, metric separation and the ad-spend boundary. A date-range default and a hint about the response shape are the only meaningful 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 75%, so dates, account narrowing, userStatement and idempotencyKey are largely documented in the schema itself. The description adds nothing about parameters — no default date range, no explanation of how accountIds narrows scope, no note that idempotencyKey is irrelevant for this read-only call. Baseline 3 fits.

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 (revenue for connected stores) and enumerates the exact measures returned: gross, refunded and net sales, order count, gross profit, break-even ROAS and customer value. It also draws a boundary against reporting_overview for ad spend, though it does not distinguish itself from near neighbours like store_orders or saas_performance.

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 one explicit exclusion plus the alternative: 'Returns nothing about ad spend: use reporting_overview for that.' That is real routing guidance, but there is no statement of when to prefer this over metrics_daily, performance_period or store_orders for revenue-adjacent questions.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is low. The description adds two things not in structured data: results are unconfirmed candidates, and calls cost no Adrails credits. It does not mention result volume, pagination, or how query narrows results.

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, action first, with the interpretive caveat and the cost note following. No repetition of the title and no filler.

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

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

With a read-only annotation set, no output schema, and schema-documented parameters, the description covers what an agent needs to call it correctly and interpret the results. The remaining gap is how the returned candidates should be piped into a launch or sizing step, which is only hinted at.

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 75% and the schema itself enumerates and explains all 11 kind values, so the schema does the heavy lifting. The description only names four of the kinds (audience, interest, language, location), leaving catalog, product-set, saved-audience, lead-form, instant-experience and page-event unmentioned outside the schema, and says nothing about query or accountIds.

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?

A specific verb ("Look up") plus a concrete resource ("actual platform audience, interest, language or location IDs") tells an agent exactly what comes back. It stops short of naming the sibling it differs from (audience_estimate), so 4 rather than 5.

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

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

"Returned candidates are not confirmed launch choices" is a genuine usage caveat that implies this is a lookup step feeding a later launch decision. However, no explicit when-to-use statement, no exclusions, and no pointer to the alternative (audience_estimate) for sizing an audience.

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

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

The annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds useful context by stating that the call is read-only, describing the returned automation fields, explaining pagination, and noting that MCP calls consume no Adrails credits.

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 the core list operation, then quickly covers pagination, alternatives, and cost. Every sentence adds actionable information, and there is no repetition or filler.

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

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

For a read-only list tool with no output schema, the description is complete enough: it names the returned fields, explains pagination, identifies alternatives for mutation and preview, and notes credit usage. The remaining parameter details are adequately covered by the input schema.

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

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

Schema coverage is 75%, so the schema already documents most parameters, including after as the previous page's nextCursor. The description reinforces pagination but does not add meaning for accountIds, userStatement, or idempotencyKey, and idempotency is irrelevant for this read-only call.

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

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

The description gives a specific verb and resource: it lists workspace automations with named return fields and templates, capped at 100. It also distinguishes this read operation from workflows_manage and workflows_preview, so an agent can select it without opening sibling schemas.

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

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

It explicitly routes write operations to workflows_manage and inspection of a proposed run to workflows_preview. Pagination guidance is also included via nextCursor and after, leaving little ambiguity about when and how to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is structured. The description adds value beyond them by stating that no messages are sent and no proposed changes are applied, plus the free/no-credits behavior — useful operational context an agent cannot get from the hints alone.

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 non-effect guarantee front-loaded and the cost note as a short trailing clause. No filler.

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

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

The input schema has a two-branch anyOf (operation=workflow with automationId+definition, versus operation=source with node+timeZone), and the description says nothing about these modes or what a preview returns (no output schema). It is adequate at the top level but incomplete for a polymorphic preview tool.

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

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

With 75% schema description coverage, the schema already documents accountIds, userStatement and idempotencyKey. The description adds nothing about the required 'input' union (the 'workflow' vs 'source' operations), which is the highest-value parameter information here. Baseline 3 applies.

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

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

States a specific verb (preview) and resource (automation or integration source) and clarifies the effect (no messages delivered, no changes applied). It never names a sibling such as workflows_list, so the differentiation is only implicit.

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

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

'Without delivering messages or applying its proposed changes' implies the pre-commit use case, but there is no explicit when-to-use rule or named alternative (e.g. 'use workflows_list to enumerate, use this before applying'). The routing signal is inferable rather than stated.

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